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Foreword 


The PL/I system is a complete software package for both applications and system 
programming. PL/I runs under the Digital Research single-user operating systems, 
CP/M® or CP/M-86®. PL/I runs in a multiuser environment, under MP/M II™, 
or MP/M-86™. This manual assumes you are familiar with your operating system and 
minimizes references to it. 


PL/I is formally based on the Subset G language defined by the ANSI PL/I Stan- 
dardization Committee X3J1. Subset G contains all the necessary application pro- 
gramming constructs of full PL/I, and discards seldom-used or redundant forms. The 
resulting language encourages good programming practices while simplifying the com- 
pilation task. 


The PL/I Language Programming Guide is divided into three parts. The first part, 
Sections 1 through 6, presents a brief introduction to the PL/I language, with emphasis 
on block structure, data types, and its various executable statements. Section 5 gives 
guidelines for developing a readable programming style. Section 6 explains the oper- 
ation of the system as a whole, and introduces you to the mechanics of compiling, 
linking, and executing programs. 


The second part, Sections 7 through 16, contains detailed sample programs that 
illustrate the useful facilities of the language, including Input/Output processing, string 
and list processing, scientific computation, and business applications. Each section 
presents general concepts, and then a detailed discussion of one or more example 
programs to illustrate the concepts. 


The third part, Section 17 through 20, presents advanced programming topics, such as 
the internal representation of data, conventions for interfacing assembly language 
programs with PL/I modules, making direct operating system calls, and writing PL/I 
programs that use overlays. 


The best way to learn any programming language is to study working examples. To 
learn PL/I, you should study these example programs along with the associated text, 
and cross-check the material with the PL/I Language Reference Manual when necessary. 
Once you understand the operation of a particular program, you can modify the 
program to enhance its operation and further your experience with the language. 
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Section 1 
Introduction 


1.1. What is PL/I? 


PL/I is a programming language that you can use to write either applications or 
system-level programs. It is formally based on the ANSI General Purpose Subset (Subset 
G) as specified by the ANSI PL/I Standardization Committee X3J1. PL/I Subset G has 
the formal structure of the full language, but in some ways it is a new language, and 
in many ways an improved language compared to its parent. 


PL/I Subset G is easy to learn and use. It is a highly portable language because its 
design generally ensures hardware independence. It is also more efficient and cost 
effective, because programs written in PL/I Subset G are easier to implement, document, 
and maintain. 


1.2 Using This Manual 


This manual is designed to help you learn PL/I by studying sample programs. If you 
have never programmed in a structured, high-level language such as PL/I, you should 
read Sections 1 through 4 first. These sections provide you with a brief introduction 
to the language. PL/I has features that are similar to other programming languages, 
but it also has its own unique constructs and syntax. 


Sections 1 through 4 outline the fundamental structure and features of PL/I in an 
informal and conceptual framework. This summary can help you become familiar with 
the overall capabilities of PL/I and encourage you to use its full power. 


Sections 1 through 4 are not a complete tutorial on PL/I programming in general. 
If you find the overview is not sufficiently detailed, you might want to read some of 
the books listed in Appendix E of the PL/I Language Reference Manual. You should 
also refer to the material in Sections 1 through 4 of the PL/I Language Reference 
Manual. 


If you are already an experienced PL/I programmer, you might want to begin with 
Section 6, which describes how to compile and link programs. 
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1.3. Notation 


The following notational conventions appear throughout this document: 


Words in capital letters are PL/I keywords or the names of PL/I programs that 
are described in the text. 


Words in lower-case letters or in a combination of lower-case letters and digits 
separated by a hyphen represent variable information for you to select. These 
words are described or defined more explicitly in the text. 


Example statements are given in lower-case. 


The vertical bar | indicates alternatives. 


@ ¥ represents a blank character. 


Square brackets [ ] enclose options. 


Ellipses . . . indicate that the immediately preceding item can occur once or any 
number of times in succession. 


Except for the special characters listed above, all other punctuation and special 
characters represent the actual occurrence of those characters. 


In text, the symbol CTRL represents a control character. Thus, CTRL-C means 
control-C. In a PL/I source program listing or any listing that shows example 
console interaction, the symbol * represents a control character. 


The acronym BIF refers to one of the PL/I built-in functions. 


Throughout this manual, program listings have brackets on the left side to 
illustrate and emphasize the block structure of the language. 


References to material in the PL/I Language Reference Manual are noted at the 
end of each section. The acronym LRM denotes Language Reference Manual. 


For example, 


References: LRM Section 3.1.1 


End of Section 1 


Section 2 
The PL/I Language 


Every PL/I program consists of one or more statements from three general categories: 


@ structural statements 
@ declarative statements 
B® executable statements 


These categories are not mutually exclusive, but provide a convenient starting point. 
The following sections describe and illustrate the statements in each general category. 


2.1 Structural Statements 


Structural statements are the foundation of any program because they define the 
logical units in a program. These logical units are called blocks. When a program 
executes, control always flows from one logical unit to another. Logical units can 
contain other logical units, causing control to flow into and out of the units. You use 
structural statements to specify the hierarchical and logical structure in a program. 


2.2 Declarative Statements 


Declarative statements always occur in a logical unit defined by a structural statement, 
and determine the environment of a logical unit. The environment is the name and 
type of all the data variables available in a logical unit. Use declarative statements to 
specify the context of the variables you want to manipulate in a logical unit. 


2.3 Executable Statements 


Executable statements manipulate storage, transfer the flow of control between log- 
ical units, control the flow of data to and from I/O devices, and perform calculations. 
Both structural statements and declarative statements serve only to create a context 
for executable statements. 
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Listing 2-1 shows a PL/I program that illustrates statements from each category. You 
need not fully understand the program or the syntax of each statement at this point. The 
program consists of distinct blocks of statements; each block is a logical unit of control. 


sample: 
[ Procedure options(main) 3 
declare 

c character(10) varying 


do§ 
Put skip list(‘Inputs ‘)3 
get list(c)3 
c = upper(c)$ /* function reference */ 
Put skip list( ‘Output: ‘9c0)5 
ends 


begin 
declare 
c float binary(24)3 


Put skip list(‘Input: ‘)3 

get list(c)3 

call output(c)$ /* subroutine invocation #/ 
end$ 


c character(10) varying 


return(translate(c»‘ABCDEFGHIJKLMNOPORSTUVWXYZ’ » 
‘abcdefghidklmnorparstuuwxyz’))$ 
end upper} 


Output: 
Procedure(c)$ 
declare 
c float binary(24)§ 


Put skip edit(c) (column(20) 1e(10+52))35 
end outputs 


upper: 
Procedure(c) returns(character(10) varying)$ 
declare 


L— end sample; 


Listing 2-1. SAMPLE PL/I Program 
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Every PL/I program must have a main procedure block. Although you can separately 
develop and compile external procedures that can be linked to and called from a main 
procedure, there can be only one main procedure block in a program. In Listing 2-1, 
the first two statements, together with the last statement, determine the outermost, or 
main block of the program. 


2.4 PL/I Blocks 


In PL/I a block can have its own local environment, and possibly an environment 
inherited from a containing block. A containing block is any block that contains another 
block. For example, in Listing 2-1 the DO-group inherits the environment of the main 
procedure block. However, the BEGIN block has its own local environment, even 
though it is contained in the main procedure block. 


In PL/I there are two types of blocks: 


@ PROCEDURE blocks 
@ BEGIN blocks 


You can nest either type of block. This means that you can put one block inside 
another, but the blocks cannot overlap. The essential difference between a PROCE- 
DURE block and a BEGIN block is the way that PL/I executes each block in the overall 
program. 


PL/I executes BEGIN blocks as they are encountered in the normal sequence of 
statements in the program. A BEGIN block ends when its corresponding END statement 
is encountered or when control passes outside the block. When control reaches a BEGIN 
block, the statements inside the block execute sequentially. Usually, when control leaves 
the block, it simply passes to a containing block or goes to the next sequential block. 
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PL/I ignores PROCEDURE blocks as they are encountered in the usual sequence of 
statements in the program. Control only passes to and enters a PROCEDURE block 
when the program invokes the procedure with a CALL statement or a function ref- 
erence. A PROCEDURE block is active when the statements inside the block are 
executing. When the statements inside the procedure finish executing, the PROCEDURE 
block returns control to the point of the call. 


For this reason, you can place a procedure anywhere in a program. It is good 


programming practice to put all procedures at the bottom of the main program. This 
makes debugging and maintaining a program easier. 


2.5 Procedures 


Every procedure consists of a procedure name, procedure header, the procedure body 
of zero or more statements, and an end statement. Figure 2-1 shows the components 
of the main procedure in the SAMPLE program. 


procedure name procedure header 


sample: 
procedure options(main); 


procedure body 


end ee 
end statement 


Figure 2-1. PL/I Procedure Components 


PL/I Programming Guide 2.5 Procedures 


If you nest procedures, they inherit the environment of containing blocks. However, 
any variable that you declare in a containing block can be redeclared, with local 
attributes, in the nested procedure. 


There are two general types of procedures in PL/I: 


® subroutine procedures 
® function procedures 


Use the CALL statement to invoke a subroutine procedure. A subroutine procedure 
performs a specific task, and optionally returns values to the invoking procedure. 


Invoke a function procedure by making a function reference. A function reference 
is simply using the name of the function in a statement. PL/I evaluates the function 
reference and replaces it with a scalar value at the point of the reference. 


Procedures are either internal or external in relation to the main procedure. An 
internal procedure is contained in the body of the main procedure, while external 
procedures are written and compiled separately from the main program. To make an 
external procedure known to the main procedure, you must declare the procedure name 
as an entry constant (see Section 3.1.3). You must also link the external procedure to 
the main procedure after both are compiled. All the procedures in the SAMPLE program 
are internal to the main procedure. 


2.6 DO-groups 


The DO-group is similar to the BEGIN block. There are several forms of the DO- 
group, and they are executable statements because they influence the flow of control. 
However, they are also considered structural statements because they define logical 
units. . 


Listing 2-1 illustrates the simplest form of the DO-group. It looks like a BEGIN 
block, but there is a crucial difference. Although a DO-group binds all the statements 
in its body into one logical unit, it cannot define a new environment. A DO-group 
cannot define new variables whose environment is limited to the body of the DO- 


group. 


2.6 Procedures PL/I Programming Guide 


A DO-group can bind only executable statements. However, a BEGIN block can 
bind both declarative statements and executable statements. The environment of a DO- 
group is determined by the environment of the block where it occurs. 


End of Section 2 
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Section 3 
Declarations 


Use declarative statements to specify the data items you want to manipulate with 
the executable statements in your program. PL/I has a rich variety of data types. In 
addition to arithmetic and string data, PL/I supports pointer, label, and entry data, 
which are generally not available in other languages. Table 3-1 shows the PL/I data 
types divided into categories and subcategories. 


Table 3-1. PL/I Data Types 


Category Subcategory 


Arithmetic FIXED BINARY 
FLOAT BINARY 
FIXED DECIMAL 


String CHARACTER 
BIT 


Control Label Variable 
Label Constant 
Entry Variable 
Entry Constant 


Pointer POINTER 


File File Variable 
File Constant 
a a sre ET 
Data Aggregates Arrays 
Structures 
SE EE 
Procedures Subroutines 
Functions 


3.1 Scalar Data PL/I Programming Guide 


All declarative statements specify either data constants or data variables. You must 
explicitly declare all data variables in a DECLARE statement, but data constants are 
usually declared implicitly by their occurrence in an executable statement. A PL/I 
variable is defined by an identifier name. The name can consist of up to thirty-one 
alphanumeric characters or underscores. The first character must be a letter. 


Usually, declarative statements, whether explicit or implicit, result in a specific allo- 
cation of storage for the data item declared. The Compiler determines the amount of 
storage required for the type of data, and associates the item with this storage. BASED 
variables are an exception because they do not necessarily force an allocation of storage 
(see Section 4.5). 


3.1 Scalar Data 


There are two main kinds of data: scalar, or single, data items, and aggregate, or 
multiple, data items. Scalar data types are the fundamental data types of the language. 


3.1.1 Arithmetic Data 


You use arithmetic data for direct numerical calculation. PL/I provides several types 
of arithmetic data, so you can match the data to the application. 


FIXED BINARY 


You can use FIXED BINARY data to represent integers. PL/I internally represents 
this data type in two’s complement binary form. The precision of a FIXED BINARY 
number is the number of bits used to represent it, independent of the sign. PL/I uses from 
1 to 15 bits, so it can represent integers in the range from —32768 to +32767. 


FLOAT BINARY 


You can use FLOAT BINARY data to represent very small or very large numbers. 
FLOAT BINARY data has a binary fractional part (called the mantissa), a binary 
exponent, and a sign. PL/I supports both single-precision and double-precision FLOAT 
BINARY numbers. The precision of a FLOAT BINARY number is the number of bits 
in the mantissa. 


Single-precision numbers can have from 1 to 24 bits, while the exponent part is 
always represented by 8 bits. The maximum range of single-precision FLOAT BINARY 
numbers in decimal is approximately 5.88 * 10**-39 to 3.40 *10**38. 
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Double-precision numbers can have from 24 to 53bits, while the exponent has 11 bits. 
The maximum range of double-precision FLOAT BINARY numbers in decimal is 
approximately 9.40 * 10**-308 to 1.80 * 10**308. 

FIXED DECIMAL 

You can use FIXED DECIMAL data to represent numbers with a fixed decimal 
point. You can also use FIXED DECIMAL data to represent integers. Internally, 
PL/I represents FIXED DECIMAL data in binary coded decimal (BCD) digits. 

FIXED DECIMAL numbers have both precision and scale. The precision is the total 
number of decimal digits used to represent the number. The scale is the number of 
decimal digits to the right of the decimal point. 

In PL/I, the precision of a FXED DECIMAL number can vary from one to fifteen, 
while the scale can vary from zero to fifteen. This arithmetic data type is particularly 
useful for commercial calculations, which require exact representations of dollars and 


cents and cannot accept the truncation errors of binary arithmetic. 


You declare an arithmetic data variable in a declaration statement of one of the 
following forms, where p is the precision and q is the scale. 


Statement: 

DECLARE identifier FIXED BINARY[(p)]; 
Example: 
declare index counter fixed binary(7)5 
Statement: 

DECLARE identifier FLOAT BINARY[(p)]; 
Example: 
declare Pi float binary(53)5 
Statement: 


DECLARE identifier FIXED DECIMAL|(pl,q])]; 
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Example: 


declare base pay fixed decimal(5:2)3 


Note: precision and scale are optional. If you omit them, PL/I supplies default values. 


You should use binary arithmetic for most numerical work, because it is faster and 
uses the least storage. If you are doing scientific work, PL/I has a complete library of 
built-in mathematical functions, which includes the trigonometric and the hyperbolic 
functions. 


3.1.2 String Data 


The ability to manipulate string variables is one of the most useful features of 
PL/I. PL/I has a complete set of built-in functions that you can use to manipulate string 
data. You declare a string variable to be either a bit string or a character string in a 
declaration of one of the following forms: 

Statement: 

DECLARE identifier CHARACTER[(n)]; 
Example: 
declare alphabet character(26)3 
Statement: 

DECLARE identifier CHARACTER[(n)] VARYING; 
Example: 
declare state character(20) varvyings 
Statement: 


DECLARE identifier BIT[(n)]; 


Example: 
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The VARYING attribute means that the character string can vary in length, but 
cannot exceed the value of n. For CHARACTER variables, the value of n can be 
between 0 and 254. If you want to manipulate longer strings, you can use one-dimen- 
sional arrays. 


Character-string constants are implicitly declared by their occurrence in a program. 
Indicate a character-string constant by enclosing it in apostrophes. If you want to 
include an apostrophe in the string, you must precede it with an extra apostrophe. 
PL/I also allows you to include control characters in a character string. 


The following are examples of character strings: 


‘Ada Lovelace’ 
‘*g “g Input Error’ 
‘Can’’t Read Previous Line’ 


Bit-string variables cannot have the VARYING attribute, and the length of a bit 
string cannot exceed sixteen. PL/I allows you to specify bit-string constants in several 
different formats. Each format corresponds to a different base, which is the number 
of bits used to represent the item. The formats for bit-string constants are: 


@ base 2 (B or B1 format) 
@ base 4 (B2 format) 

@ base 8 (B3 format) 

@ base 16 (B4 format) 


In each of the formats, write the bit-string constant as a string of numeric digits for 
the desired base, enclosed in apostrophes and followed by the format type. The fol- 
lowing are examples of the four formats: 


*1O1iT1*6 equals 101111 
*“101111°’B1 equals LODtT1 
*Za0'B2 equals 101111 
‘37'BS equals 101111 
‘2F‘B4 equals 00101111 


3.1.3 Control Data 


There are two types of control data: 


m LABEL data 
m ENTRY data 
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LABEL data allows you to reference individual statements in your program. PL/I 
not only allows individual statements to have labels, it also allows you to declare label 
variables. This means that you can manipulate labels in your program like any other 
valid data items. 


The value of a label variable is always a label constant, implicitly defined and declared 
by its occurrence as a label of a statement in the program. PL/I allows you to subscript 
label constants. You can also declare arrays of label variables. 


You can use label variables to manipulate the flow of control between logical units of 
a program. It is better programming practice to do this without using GOTOs and 
labels. 


The following program is a whimsical example of label variables. 


r-chase_your tail: 
Procedure options(main) 3 
declare 

wherever labels 


there: 

wherever = here$ 
here: 

wherever theres 
goto wherevers 


Lend chase your tails 


PL/I also supports a powerful data type called ENTRY data. ENTRY data allows 
you to reference procedures just like any valid data item. You can declare an entry 
variable then assign it a value. The value of an entry variable is an entry constant. 


Entry constants are the labels of procedures, rather than labels of executable state- 
ments. An entry constant is implicitly declared by its appearance as a label to an 
internal procedure. 


When you declare an entry variable, you must explicitly define the type of entry 
constant that the variable can assume. When you explicitly declare an entry constant, 
you must declare it with the same attributes as the procedure it references. 
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The programs shown in Listing 3-1 illustrate these concepts. Listing 3-1a shows an 
external procedure called a. Listing 3-1b shows the program CALL, that references a. 
In CALL, f is an entry variable that assumes three different constant values. To create 
an executable program, you compile each module separately then link them together. 


ar 
Procedure(x) returns(float)s /# external procedure #/ 
declare x floats 
return(x/2)5 

end ai 


Listing 3-1a. External Procedure A 


calls 
Procedure ortions(main)§ 
declare 
£(3) entry(float) returns(float) variable» 
a entry(float) returns(float)$ /* entry constant /* 
declare 
i fixeds x floats 


(1) 
(2) 
f(3) 


do i 

Put skip list(‘Tyre x ‘)3 

get list(x)3 

Put list(*f(*sis’d=% sf Cid(xd)s 
ends 
stops 


b: 
Procedure(x) returns(float)$ /# internal procedure */ 
declare x floati 
return (2*x + 1)3 

end bj 


Ge 
Procedure(x) returns(float)s /* internal Procedure 
declare x floats 
return(sin(x))$ 

end c3 


L end call; 


Listing 3-1b. The CALL Program 


TAL RESEARCH 
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3.1.4 Pointer Data 


Pointer data allows you to manipulate the storage allocated to variables. The value 
of a pointer variable is the address of another variable. 


3.1.5 File Data 


File data items describe and provide access to the data associated with an external 
device. File data items are either file constants or variables. You must always assign a 
file constant to a file variable before you access the data in the file. 

Declare file data in a declaration statement in one of the following forms: 
Statement: 

DECLARE identifier FILE; 
Example: 
declare current _transaction files 
Statement: 

DECLARE identifier FILE VARIABLE; 
Example: 
declare f(2) file variables 

The executable statements used for file access determine the file attributes. (Section 
4.3 describes file-handling and I/O operations.) 


3.2 Data Aggregates 


A data aggregate is a combination of data types that forms a data type on a higher 
level. There are two kinds of aggregates in PL/I: 


@ arrays 
@ structures 
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3.2.1 Arrays 

An array is a subscripted collection of data items of the same data type. PL/I allows 
arrays of arithmetic values, character strings, bit strings, label constants, entry con- 
stants, pointers, files, or structures (see Section 3.2.2). 

The following are examples of array declarations: 
declare test scores(100)3 
declare A(4:5)35 
declare A(1:4s2:510:10)3 

You make direct references to individual elements of an array by using a subscripted 
variable reference. PL/I also allows you to make cross-sectional references, with the 
restriction that the reference must specify a data component whose storage is connected. 
For example, using the following declarations, 
declare A(5Ss2) fixed binary3 
declare B(5s2) fixed binarys 


you can visualize the arrays pictured in Figure 3-1: 


A B 


nAPRWN PR 
ARWN PR 


Figure 3-1. Arrays 
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In this example, A and B are identical in size and attributes. Therefore, an assignment 
such as 


A(3) = B(4)3 
is valid because the cross-sectional reference specifies connected storage. 


3.2.2 Structures 


A structure is a very different type of data aggregate than an array. A structure is 
hierarchical, much like a tree, where the leaves of the tree, called nodes, can be various 
PL/I data types. 


Each node of the tree, beginning with the root, has a name and a level number. The 
level number indicates the level of each node in relation to the root. The following 
example illustrates a structure declaration. 


declare 
1 employee» 
2 name address» 
3 names 
4 first character(1i0)» 
4 middle initial character(1),; 
4 last character(20)» 
3 address,» 
4 street character(40) + 
4 city character(10)» 
4 state character(2)+s 
4 zip_code character(S)» 
Position» 
3 department no character(3)» 
3 Job _ title character(20) » 
Salary fixed decimal(8s2)+ 
number of dependents fixeds 
health plan bit(1)» 
date hired character(8) 3 
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Figure 3-2 illustrates the hierarchy of levels that corresponds to the declaration. 


name first 
= — middle_ initial 


last 


employee name_address 


address street 
city 
state 
zip_code 


IR department_no 
job_title 


salary 
number_of_dependents 
health_plan 

date_hired 


Figure 3-2. Structure Declaration Hierarchy 
Nodes on each level can also determine a structure. Such a substructure is a member 


of the main structure. You can give the BASED attribute to the main structure with 
the result that all the members of the structure receive the attribute. 


Structures are powerful tools because they enable you to group logically related data 
items that might not have the same data type. Thus, structures allow you to characterize 
and manipulate logical objects in your program to more closely resemble real data. 


End of Section 3 
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| Section 4 
Executable Statements 


py UOnIaS 


The category of executable statements is divided into several subcategories based on 
| the type of function that the statement performs. The subcategories are: 


assignment statements 

sequence control statements 

V/O and file-handling statements 
memory management statements 
condition processing statements 

preprocessor statements 

null statements 


4.1 Assignment Statements 


An assignment statement places the value of an expression into the storage location | 
associated with a variable. | 


An expression is a combination of operators, operands, function references, and 
parentheses that control the order of evaluation of the expression. 
| 


In PL/I, the assignment statement has the form: | 


variable reference = expression; 
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An expression in PL/I can be fairly complicated. The simplest type of variable ref- 
erence is instantiating the variable name, which means to assign the variable a specific 
value. A variable reference can also be a reference to a data aggregate, or to a component 
of the aggregate. If the variable is BASED, a pointer-qualified reference might be 
required (see Section 4.5.1). 


PL/I also allows certain built-in functions such as UNSPEC and SUBSTR to appear 
as targets on the left side of assignment statements. When they appear as variables in 
this context, they are called pseudo-variables. 


Expressions can be computational. This means that the expression involves arithmetic 
or string values of the various types and their respective operators. Expressions can 
also be noncomputational, involving comparisons of noncomputational data types such 
as labels, entry constants, and pointers. 


PL/I allows computational expressions of different data types, and automatically 
performs conversion between the various types following a standard set of default rules. 
You should become familiar with the automatic conversion rules and the properties 
of the built-in conversion functions (see Section 4 LRM). 
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The following sequence of code illustrates some simple examples of assignment 
statements. These examples also illustrate some of the ways you can reference a variable 
in PLA. Such references can also occur in expressions, although PL/I limits aggregate 
expressions to comparison for equality. 


—assign: 
Procedure options(main)$ 
declare 
P Pointers 
i fixed binary(7)» 
r bit(16)» 
s bit(16) based» 
(usu) float binary(24)+ 
A(592) character(2)+ 
B(592) character(2)+ 
C character(20)» 
1 ws 
2x fixed binary: 
2 y¥ bit(16)» 
i 24 
2 x fixed binary» 
2 y bit(16)3 


u =u + vi /* simple assignment #*/ 

A = BS /* array agdydregate assignment */ 

A(3) = B(4)3 /* cross-sectional reference */ 

w= z3} /* structure aggregate assignment */ 

Pp -> s = (r = wey)s /* Pointer-aualified reference */ 

WeX = WeX + 2x5 /* Partially-qualified aggregate reference */ 
unspec(wey) = unspec(A(Ss1))5 /* pseudo-variable reference */ 
substr(Criti»3) = substr(C.1093)i /* pseudo-variable reference */ 
A(2*i+1) = B(4)3 /* variable is expression */ 


Lend assigni 


4.2 Sequence Control Statements 


You can use sequence control statements to alter the normal sequential flow of 
control. In PL/I, sequence control statements perform unconditional branching, con- 
ditional branching, iteration, branch and return through procedure invocation, and a 
more unique construct called condition processing. 
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4.2.1 Iteration 


PL/I provides an extensive variety of iteration control in the various forms of the 
DO statement. For example, you can perform iteration not only with an arithmetic 
control variable, but also with a pointer control variable that is moving through a 
linked list of pointers. 


The following diagrams illustrate the basic forms of the DO statement and the flow 
of control that they induce. The values e1, e2, e3, and e4 represent any scalar expressions. 


F 
DO WHILE(e); 
: T 
END; , 


DO i = el REPEAT(e2); 


END; 


Figure 4-1. Forms of the DO Statement 
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DO i = el REPEAT(e2) WHILE(e3); 


END; 


DO i = el TO e2 BY e3 WHILE(e4); 


END; 


Figure 4-1. (continued) 
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4.2.2 Procedure Invocation 


A branch and return occurs as the result of a procedure invocation. As we have seen, 
in PL/I there are two types of procedures: subroutine procedures and function pro- 
cedures. There are two corresponding forms of invocation. 


You invoke a subroutine procedure with a CALL statement, but you invoke a function 
procedure by using its name in an expression. You call a subroutine procedure for a 
specific reason, such as altering the value of variables passed to the procedure, or input 
and output. You always invoke a function procedure in an expression to return a scalar 
data item. In PL/I, both types of procedures can be recursive, which means they can call 
themselves. 


There is an important distinction between a procedure definition and a procedure 
invocation. A procedure definition is a declarative statement; a procedure invocation 
is an executable statement. The data items you pass to the procedure when you invoke 
it are called the actual parameters. The actual parameters are distinguished from the 
formal parameters you give in the procedure definition. Thus, the actual parameters 
are the parameters as they are known in the invoking block, while the formal parameters 
are the corresponding parameters as they are known in the invoked block, the procedure. 


4.2.3 Parameter Passing 


In PL/I, you can pass parameters by reference or by value. You pass them by reference 
if the actual parameters and the formal parameters share storage. You pass them by 
value if the value of the formal parameter is held as a local copy of the value of the 
actual parameter. 


Under PL/I rules, the formal parameter and actual parameter always share storage 
if they have identical attributes. If the actual parameter is an expression, or if its data 
attributes do not match those of the corresponding formal parameter, then the param- 
eter is passed by value. PL/I passes the parameter by value if you enclose the formal 
parameter in parentheses in the procedure header statement of the procedure definition. 
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A procedure is an independent logical unit that performs a specific function. If you 
carefully define the specific function that the procedure performs and the parameters 
that it expects from the invoking environment, you can divide the design, coding, and 
debugging of the overall program into separate units. 


If you pass a parameter by reference to conserve storage, be aware that the invoked 
procedure can change the value of a variable outside its local environment. If you want 
to assure that the procedure does not change a variable outside its local environment, 
then you must pass the parameters by value and use extra storage. 


Parameter passing is a trade-off between the amount of storage available on your 
system and the level of modularity and isolation you want in your program. There are 
three alternatives for parameter passing, characterized as the high, middle, and low 
road. The skeletal program in Listing 4-1 illustrates the concepts they represent. 


In the low road, you pass by reference but pay close attention to the possible side 
effects that can result. The advantage of this method is that it conserves storage. 


In the middle road, you pass by value, enclosing the actual parameter in parentheses 
at the point of invocation in the CALL statement or function reference. 


In the high road, you declare a duplicate variable for each formal parameter in the 
procedure definition. You then assign the corresponding formal parameter to its dupli- 
cate, and use the duplicate as a local copy in the procedure. Equally you can enclose 
the formal parameter in parentheses in the procedure header. The high road is least 
efficient in its use of storage. 
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main: 
Procedure options(main) 3 
declare 
a float binary 
call low sub(a)i /* pass by reference */ 
call middle sub((a))s /* pass by value */ 
’ 
call high _sub(a)i /* pass by reference */ 
low sub: 
Procedure(x)$ 
declare 
x float binary 
1 
i» 


end low subi 


middle sub: 
Procedure(x)3 
declare 
x float binary; 
+ 


end middle subj 


high sub: 
Procedure(x)3 
declare 
(xomy_x) float binaryé 
my xX = x3 /# reassign using local variable #/ 


end high subi 


end mains 


Listing 4-1. Parameter Passing 
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4.2.4 Conditional Branch 


PL/I provides a conditional branch in the form of an IF statement. The conditional 
branch has one of the following forms, 


IF condition THEN group 
IF condition THEN group-1 ELSE group-2 


where the condition is a scalar expression that PL/I evaluates and reduces to a single 
value, and the groups are either single statements, DO-groups, or BEGIN blocks. 


You can nest IF statements, in which case PL/I matches each ELSE with the innermost 
unmatched IF-THEN pair. However, you can use NULL statements following an ELSE 
to force an arbitrary matching of ELSE statements with IF-THEN pairs. (See Section 
4.7 NULL Statements.) 


4.2.5 Unconditional Branch 


PL/I provides an unconditional branch in the form of a GOTO statement. The 
unconditional branch has one of the following forms: 


GOTO _label_constant; 
GOTO _label_variable; 


Because PL/I is block-structured, certain rules apply to the use of the GOTO. The 


target label must be in the same block containing the GOTO, or in a containing block. 
You cannot transfer control to an inner block. 


4.3. I/O and File-handling Statements 
The executable I/O statements provide PL/I with a device-independent input/output 
system that allows a program to transmit data between memory and external devices. 


To understand the I/O statements, you must first know about files and their attributes. 


The collection of data elements that you transmit to or from an external device is 
called the data set. The corresponding internal file constant or variable is called a file. 
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As with other data items, you must declare files before you use them in a program. 
The general form of a file declaration is, 


DECLARE file_id FILE [VARIABLE]; 


where file_id is the file identifier. If you do not include the optional VARIABLE attrib- 
ute, the declaration defines a file constant. With the VARIABLE attribute, the decla- 
ration defines a file variable that can take on the value of a file constant through an 
assignment statement. You must assign a file constant to a file variable before you can 
perform any I/O operations. 


4.3.1 Opening Files 


PL/I requires that a file be open before performing any I/O operations on the data 
set. You can open a file explicitly by using the OPEN statement, or implicitly by 
accessing the file with the following I/O statements: 


@ GET EDIT 

@ PUT EDIT 
GET LIST 
PUT LIST 
READ 
WRITE 
READ Varying 
WRITE Varying 


The general form of the OPEN statement is, 
OPEN FILE(file_id) [file-attributes]; 


where file_id is the file identifier that appears in a FILE declaration statement, and file- 
attributes denotes one or more of the following: 


# STREAM | RECORD @ TITLE 

@ PRINT @ ENVIRONMENT 
= INPUT | OUTPUT | UPDATE @ PAGESIZE 

m= SEQUENTIAL | DIRECT @ LINESIZE 

m KEYED 
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Multiple attributes on the same line are conflicting attributes, so you can only specify 
one attribute. The first attribute listed is the default attribute. All the attributes are 
optional; you can specify them in any order. 


A STREAM file contains variable length ASCII data. You can visualize it as a stream 
of ASCII character data, organized into lines and pages. Each line in a STREAM file 
is determined by a linemark, which is a line-feed or a carriage return/line-feed pair. 
Each page is determined by a pagemark, which is a form-feed. Generally, you must 
convert the data in a STREAM file from character form to pure binary form before 
using it. ED automatically inserts a line-feed following each carriage return, but files 
that PL/I creates can contain line-feeds without preceding carriage returns. In this case, 
PL/I senses the end of the line when it encounters the line-feed. 


A RECORD file contains binary data. PL/I accesses the data in blocks determined 
by a declared record size, or by the size of the data item you use to access the file. A 
RECORD file must also have the KEYED attribute, if you use FIXED BINARY keys 
to directly access the fixed-length records. 


The PRINT attribute applies only to STREAM OUTPUT files. PRINT indicates that 
the data is for output on a line printer. 


For an INPUT file, PL/I assumes that the file already exists when it executes the 
OPEN statement. When it executes the OPEN statement for an OUTPUT file, PL/I 
also creates the file. If the file already exists, PL/I first deletes it, then creates a new 
one. 


You can read from and write to an UPDATE file. PL/I creates an UPDATE file, if it 
does not exist, when executing the OPEN statement. An UPDATE file cannot have the 
STREAM attribute. 


You access SEQUENTIAL files sequentially from beginning to end, but you access 
DIRECT files randomly using keys. PL/I automatically gives DIRECT files the RECORD 
attribute. PL/I also requires you to declare all UPDATE files with the DIRECT attribute, 
so you can locate the individual records. 
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A KEYED file is simply a fixed-length record file. The key is the relative record 
position of the record within the file based upon the fixed record size. You must use 


keys to access a KEYED file. PL/I automatically gives KEYED files the RECORD 
attribute. 


The TITLE(c) attribute defines the programmatic connection between an internal 
filename and an external device or a file in the operating system’s file system. If you 
omit the TITLE attribute, PL/I assigns the default title file_id.DAT, where file_id is 
the file identifier specified in the OPEN statement. 


If the character string c specifies a disk file, it must be in the form, 
d:filename.typ;password 


where the drive code d, the filetype, and the password are all optional. You must specify 
a filename. The filename cannot be an ambiguous wildcard reference. 


You can also specify $1 or $2 for both the filename and filetype. $1 gets the first 
default name from the command line, $2 gets the second default name. 


The ENVIRONMENT attribute defines fixed record sizes for RECORD files, internal 
buffer sizes, the file open mode, and the level of password protection. You can open 
a file in one of three modes: Locked, Read-Only, or Shared. Locked is the default 
mode, and means that no other user can access the file while it is open. Read-Only 
means that other users can access the file, but only to read it. Shared mode means that 
other users can also simultaneously open and access the file. You can use the built-in 
LOCK and UNLOCK functions to lock and unlock individual records in the file, so 
there are no collisions with other users. 


If you assign a password to a file, you can also assign the level of protection that 
the password provides. The levels of protection are: Read, Write, and Delete. Read 
means that you must supply the password to read the file. Write means that you can 
read the file, but you must supply the password to write to the file. Delete means that 
you can read the file or write to it, but you cannot delete the file without the password. 


The LINESIZE attribute applies only to STREAM files, and defines the maximum 
number of characters in the input or output line length. The PAGESIZE attribute 
applies only to STREAM OUTPUT files, and defines the number of lines per page on 
output. 
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4.3.2 File Attributes 


PL/I controls all file transactions through an internal data structure called the File 
Parameter Block (FPB). The FPB contains information about the file, such as whether 
it is open or closed, the external device or file associated with the file, the current line 
and column, or record being accessed, and the internal buffer size. The FPB also contains 
a File Descriptor that describes the file’s attributes. These attributes in turn describe 
the allowable methods of access. Table 4-1 summarizes the valid attributes that you 
can assign to a file, either through an explicit OPEN statement, or implicitly by an 
I/O access statement. 


Table 4-1. PL/I Valid File Attributes 
STREAM INPUT ENVIRONMENT TITLE LINESIZE 


STREAM OUTPUT ENVIRONMENT TITLE LINESIZE PAGESIZE 


STREAM OUTPUT PRINT ENVIRONMENT TITLE LINESIZE PAGESIZE 


RECORD INPUT SEQUENTIAL ENVIRONMENT TITLE 
RECORD OUTPUT SEQUENTIAL ENVIRONMENT TITLE 
RECORD INPUT SEQUENTIAL KEYED ENVIRONMENT TITLE 
RECORD OUTPUT SEQUENTIAL KEYED ENVIRONMENT TITLE 
RECORD INPUT DIRECT KEYED ENVIRONMENT TITLE 
RECORD OUTPUT DIRECT KEYED ENVIRONMENT _ TITLE 


RECORD UPDATE DIRECT KEYED ENVIRONMENT TITLE 
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4.3.3 Implied Attributes 


If you do not open a file with explicit attributes, PL/I determines the attributes from 
the type of I/O statement you use to access the file. Table 4-2 summarizes the attributes 
implied by each of the I/O statements. In the following table, f is a file constant, x is 
scalar or aggregate data type that is not CHARACTER VARYING, and k is a FIXED 
BINARY key value. 


Table 4-2. File Attributes Associated With I/O Access 


I/O Statement Implied Attributes 


GET FILE(f) LIST STREAM INPUT 
PUT FILE(f) LIST STREAM OUTPUT 
GET FILE(f) EDIT STREAM INPUT 
PUT FILE(f) EDIT STREAM OUTPUT 
READ FILE(f) INTO(v) STREAM INPUT 


WRITE FILE(f) FROM(v) STREAM OUTPUT 


READ FILE(f) INTO(x) RECORD INPUT SEQUENTIAL 


READ FILE(f) INTO(x) KEYTO(k) RECORD INPUT SEQUENTIAL KEYED 
ENVIRONMENT (Locked, Fixed(i)) 


READ FILE(f) INTO(x) KEY(k) RECORD INPUT DIRECT KEYED 
ENVIRONMENT (Locked, Fixed(i)) 


RECORD UPDATE DIRECT KEYED 
ENVIRONMENT (Locked, Fixed(i)) 


WRITE FILE(f) FROM(x) RECORD OUTPUT SEQUENTIAL 


WRITE FILE(f) FROM(x) KEYFROM(k) RECORD OUTPUT DIRECT KEYED 
ENVIRONMENT (Locked, Fixed(i)) 


RECORD UPDATE DIRECT KEYED 
ENVIRONMENT (Locked,Fixed(i)) 
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4.3.4 Closing Files 


The CLOSE statement disassociates the file from the external data set. The form of 
the CLOSE statement is, 


CLOSE FILE(file_id); 


where file_id is a file constant for which PL/I clears the internal buffers, records all 
the data on the disk, and closes the file at the operating system level. You can subse- 
quently reopen the same file using the OPEN statement. PL/I automatically closes all 
open files at the end of the program or upon execution of a STOP statement. 


4.3.5 File Access Methods 


PL/I supports two methods of file access: 


@ STREAM I/O 
@ RECORD I/O 


There are three different kinds of STREAM I/O: 


@ LIST-directed uses the GET LIST and PUT LIST statements, which transfer a list 
of data items without any format specifications. 


@ Line-directed uses the READ and WRITE statements, which allow you to access 
variable-length CHARACTER data in an unedited form. These statements might 
not be available in other implementations of PL/I. 


@ EDIT-directed uses the GET EDIT and PUT EDIT statements, which allow 
formatted access to character data items. 


EDIT-directed I/O is similar to list-directed I/O except that it writes data into 
particular fields of the output line, as described by a list of format items. The data list 
specifies a number of values to write in fixed fields defined by the format list. 


The format list can contain two kinds of format items: data format items and control 
format items. PL/I pairs each element of the data list with a data format item in the 
format list. The format item determines how PL/I interprets the data element. PL/I 
executes control format items as they are encountered in the format list. 
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You can precede any format item with a positive constant integer value, not exceeding 
254, that determines the number of times to apply the format item or group of format 
items. 


4.3.6 Data Format Items 


The following examples show the various format items you can use in a GET EDIT 
or PUT EDIT statement. 


A[(w)] 
The A format reads or writes the next alphanumeric field whose width is specified 


by w, with truncation or blank padding on the right. If you omit w, the A format uses 
the size of the converted character data as a field width. 


Bin][(w)] 


The B format reads or writes bit-string values. n is the number of bits used to repre- 
sent each digit. w is the field width that you must include on input. 


E(w(,d]) 


The E format reads or writes a data item into a field of w characters in scientific 
notation, with maximum precision allowed in the field width. w must be at least 8. 


F(w([,d]) 


The F format reads or writes fixed-point arithmetic values with a field width of w 
digits, and d optional digits to the right of the decimal point. 


4.3.7. Control Format Items 


LINE(In) 
Moves to the line In in the data stream before writing the next data item. 


COLUMN (nc) 


Moves to column position nc in the data stream before reading or writing the next 
data item. This can flush the current line. 
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PAGE 

Performs a page eject for PRINT files. 
SKIP{(nl)] 

Skips nl lines before reading or writing the next data item. 
X(n) 


Advances n blank characters into the data stream before reading or writing the next 
data item. 


R(fmt) 


Specifies a remote format. This means that the format is specified elsewhere in a 
FORMAT statement. 


4.3.8 Predefined Files 

PL/I has two predefined file constants called SYSIN, the console keyboard, and 
SYSPRINT, the console output display. These files do not need to be declared unless 
you make an explicit reference to them in an OPEN or I/O statement. 


SYSIN has the default attributes: 


STREAM INPUT ENVIRONMENT(LocKked »sBuff(128)) TITLE(‘$CON’) 
LINESIZE(80) PAGESIZE(0) 


SYSPRINT has the default attributes: 


STREAM PRINT ENVIRONMENT (Locked »Buff(128)) TITLE(*‘$CON’) 
LINESIZE(80) PAGESIZE(0) 


4.4 Condition-processing Statements 


PL/I has several features that make it ideal for applications programming. One of 
these features is its capability for condition processing. In most languages, the program 
cannot recover from run-time error conditions, such as an invalid data conversion— 
control reverts to the operating system. 
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Because PL/I is designed as a production-programming language, it has various 
features that allow you to intercept run-time errors, program a response, and recover 
control. These features are collectively called condition processing. 


PL/I provides condition processing with these executable statements: 


a ON 
@ REVERT 
@ SIGNAL 


4.4.1. The ON Statement 


Use the ON statement to intercept and program a response to a run-time condition 
signaled by the system, or by the execution of a SIGNAL statement. The ON statement 
is an executable statement that defines the response. It has the form, 


ON condition on-body; 


where condition is one of the major condition categories, with or without a subcode 
(see Section 4.4.4). The on-body is a PL/I statement or statement group that you process 
when the condition occurs. 


If the subcode is not present, then PL/I processes the ON statement when any of the 
subcode conditions occur. This is equivalent to subcode 0. The file conditions must 
have a file reference describing the file for which the condition is signaled. 


4.4.2 The REVERT Statement 
Use the REVERT statement to disable the ON condition set by the ON statement. 
This is important because you can have only sixteen ON conditions set without over- 
flowing the condition code area. If overflow happens, the PL/I run-time system stops 
processing. The form of the REVERT statement is: 
REVERT condition; 


PL/I automatically reverts an ON condition set in a given block when control leaves 
the environment of that block. 
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4.4.3 The SIGNAL Statement 


The SIGNAL statement allows you to activate the response for a condition. The 
form of the SIGNAL statement is: 


SIGNAL condition; 


4.4.4 Condition Categories 


The condition categories describe the various conditions that the run-time system 
can signal or that your program can signal by executing a SIGNAL statement. 


There are nine major condition categories with subcodes, some of which are system- 
defined, and some of which you can define yourself. Table 4-3 shows the predefined 
subcodes. 


Table 4-3. PL/I Condition Categories and Subcodes 


Type Meaning 


ERROR 


ERROR (0) 
ERROR(1) 
ERROR(2) 
ERROR(3) 
ERROR(4) 
ERROR(5) 
ERROR(6) 
ERROR(7) 
ERROR(8) 
ERROR(9) 
ERROR( 10) 
ERROR( 11) 
ERROR( 12) 
ERROR(13) 
ERROR(14) 
ERROR( 15) 
ERROR(16) 


Any ERROR subcode 

Data conversion 

I/O Stack overflow 
Function argument invalid 
V/O Conflict 

Format stack overflow 
Invalid format item 

Free space exhausted 
Overlay error, no file 
Overlay error, invalid drive 
Overlay error, size 

Overlay error, nesting 
Overlay error, disk read error 
Invalid OS call 
Unsuccessful Write 

File Not Open 

File Not Keyed 
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Table 4-3. (continued) 


FIXEDOVERFLOW 


FIXEDOVERFLOW (0) 


OVERFLOW 


OVERFLOW(0) 
OVERFLOW( 1) 
OVERFLOW( 2) 


UNDERFLOW 


UNDERFLOW(0) 
UNDERFLOW(1) 
UNDERFLOW(2) 


ZERODIVIDE 


ZERODIVIDE(O) 
ZERODIVIDE(1) 
ZERODIVIDE(2) 
ZERODIVIDE(3) 


ENDPAGE 


Meaning 


Any FIXEDOVERFLOW subcode 


Any OVERFLOW subcode 
Floating-point operation 
Float precision conversion 


Any UNDERFLOW subcode 
Floating-point operation 
Float precision conversion 


Any ZERODIVIDE subcode 
Decimal divide 
Floating-point divide 
Integer divide 


In addition to these predefined system condition subcodes, you can define certain 
subcodes for a specific application, test for the desired condition, and then use the 
SIGNAL statement to signal the condition. 
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4.4.5 Condition Processing Built-in Functions 


PL/I provides certain built-in functions to help handle conditions when they occur. 
These functions are: 


ONCODE 
ONFILE 
ONKEY 
PAGENO 
LINENO 


The ONCODE function returns the subcode of the most recently signaled condition, 
or zero if no condition has been signaled. 


The ONFILE function returns the internal filename of the file involved in an I/O 
operation that signaled a condition. 


The ONKEY function returns the value of the last key involved in an I/O operation 
that signaled a condition. 


The PAGENO and LINENO functions return the current page number and line 
number for a PRINT file named as the parameter. 


4.5 Memory Management Statements 


Every variable in a PL/I program has a storage-class attribute. The storage class 
determines how and when PL/I allocates storage for a variable, and whether the variable 
has its own storage or shares storage with another variable. 


PL/I supports three different storage classes: 


w STATIC 
@ AUTOMATIC (the default in PL/I) 
@ BASED 


PL/I treats AUTOMATIC storage as STATIC storage, except in procedures marked 
as RECURSIVE. The Compiler allocates storage for STATIC variables prior to exe- 
cution, and the storage remains allocated as long as the program is running. You can 
use the INITIAL attribute to assign initial constant values to STATIC data items. 
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Note: only STATIC variables can have the INITIAL attribute, to be compatible with 
the ANSI Subset G PL/I standard. 


Storage-class attributes are properties of scalars, arrays, major structure variables, 
and file variables. You cannot assign storage-class attributes to entry names, file con- 
stants, or members of data aggregates. 


4.5.1. BASED Variables and Pointers 


The Compiler does not allocate storage for variables with the BASED storage class. 
A based variable is a variable that describes storage that you must access with a pointer. 
The pointer is the location where the storage for the based variable begins, and the 
based variable itself determines how PL/I interprets the contents of the storage beginning 
at that location. Thus, the pointer and the based variable taken together are essentially 
equivalent to a nonbased variable. 


You can visualize a based variable as a template that overlays the storage specified 
by its base. Thus, a based variable can refer to storage allocated for the based variable 
itself, or to storage allocated for other variables. 

The format of the BASED variable declaration is, 

DECLARE name BASED[(pointer-reference)]; 


For example, 


declare A(5+5) character(10) based3 
declare bit vector bit(8) based(p)3 


where the pointer reference is an unsubscripted POINTER variable, or a function call, 
with zero arguments, that returns a POINTER value. 


A pointer-qualified reference can be either implicit or explicit. When you declare a 
variable as BASED without a pointer reference, then each reference to the variable in 


the program must include an explicit pointer qualifier of the form, 


pointer-exp -> variable 
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When you declare a variable as BASED with a pointer reference, then you can 
reference it without a pointer qualifier. The run-time system reevaluates the pointer 
reference at each occurrence of the unqualified variable using the pointer expression 
given in the variable declaration. The following code sequence illustrates the concept 
of based variables. 


declare 
P Pointers 
a character(1i28) + 
b(128) character(1i) based(Pp)» 
c(0:127) bit(8) based(p)+s 
d(64) bit(1G) based(p);s 
e(8+,0:15) bit(8) based(p)s 


’ 


P = addr(a)s 


In this example, after pointer p is set to the address of a, each of the variables b, c, 
d, and e refers to the same 128 bytes of storage occupied by the variable a, although 
they do so in different ways. Thus, the variables b, c, d, and e overlay the variable a. 


There is one important point to consider here. The overlays illustrated above depend 
on the method a particular processor uses to internally represent and store the data 
items. Such code makes a program implementation-dependent. For example, in imple- 
mentations other than PL/I, the internal representation of an array could include some 
header bytes in addition to the bytes used to represent the data elements. In each case, 
you must investigate the internal representation before using based variables to overlay 
other data types. 
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4.5.2 The ALLOCATE Statement 


The ALLOCATE statement explicitly allocates storage for a BASED variable. The 
ALLOCATE statement takes the form: 


ALLOCATE based variable SET(pointer variable); 
For example, 
allocate input_buffer set(buffer ptr)s 


The run-time system obtains sufficient memory for the based variable from the free 
storage area and then sets the pointer variable to the address of this memory segment. 


4.5.3 The FREE Statement 


The FREE statement releases the storage allocated to a BASED variable. The FREE 
statement takes the form: 


FREE [pointer variable ->] based variable; 
For example, 


free input buffers 


Note: the pointer variable reference is optional if you declared the based variable with 
a pointer reference. 
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The following code sequence illustrates the use of the ALLOCATE and FREE statements. 


declare 
(Praer) Pointers 
a character based, 
b fixed based(r)$ 
allocate a set(P) 
allocate b set(r) 
allocate a set(q) 


free P -> a3 
free gq ->} a3 
free b3 


4.6 Preprocessor Statements 


Preprocessor statements allow you to include other files and modify the source 
program at compile time. 


The %INCLUDE statement copies PL/I source from another file at compile time. 
The %INCLUDE statement is useful for filling in declarations that are repeated through- 
out a program. The %INCLUDE statement takes the form: 

% INCLUDE ‘filespec’; 


For example, 


“include ‘fcb.dcel’s 
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The %REPLACE statement allows you to replace identifiers by literal constants 
throughout the text of a PL/I program at compile time. The % REPLACE statement 
takes the form: 

% REPLACE identifier BY literal constant; 


You can put more than 1 identifier-constant pair in a single % REPLACE statement 
by separating the pairs with commas. 


For example, 
“rePlace 
true by ‘1i’bs 
false by ‘O’b3 


4.7 Null Statements 


The null statement does not perform any action. Its form is simply: 


> 


You can use the null statement as the target of a THEN or ELSE clause in an IF 
statement. In the following example, 


if x > average then 
Soto Print_it3 
elses 


no action takes place when x is less than or equal to average, and the sequence of 
execution continues at the statement following the ELSE. As another example, consider 
this statement: 


on endpage(report file); 


Here, no action takes place when PL/I processes the ON-unit for ENDPAGE, and the 
V/O statement that signaled the condition continues. 
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You can also use null statements to give more than one label to the same executable 
statement. For example, 


A:; 
B: statement-1; 
statement-2; 


End of Section 4 
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Section 5 
Programming Style 


PL/I is a free-format language. You can write programs without regard to column 
positions and specific line formats. Each line can be up to 120 characters long terminated 
by a carriage return, and logically connected to the next line in sequence. The Compiler 
simply reads the source program from the first through the last line, disregarding line 
boundaries. 


In exchange for this freedom of expression, you should adhere to some stylistic 
conventions, so that your programs can be easily read and understood by other pro- 
grammers. A professional program not only produces the correct output, but is con- 
sistent in form and divided into logical segments that are easy to comprehend. A 
logically structured program is also much easier to debug. A well-constructed program 
is appreciated for its form and its function. 


There are many stylistic conventions in use by individual programmers. The following 
rules illustrate one set of conventions that are used throughout the examples in this 
guide. Listing 5-1 illustrates the conventions presented in this section. 


5.1 Case 


You can write PL/I programs in either upper- or lower-case. Internally, the PL/I 
Compiler translates all characters, outside of string quotes, to upper-case. Using lower- 
case throughout programs generally improves readability. 


5.2 Indentation 


Use indentation throughout your program to set off various declarations and state- 
ments. To simplify indentation, the Compiler expands tabs (‘I characters) to every 
fourth column position. Some text editors expand tabs to multiples of eight columns, 
so the line appears wider during the edit and display operations. The Compiler issues 
the TRUNC (truncate) error if the expanded line length exceeds 120 columns. 


Program statements start at the outer block level in the first column position. Each 
successive block level, initiated by a DO-group, BEGIN, or PROCEDURE block, starts 


49 


5.2 Indentation PL/I Programming Guide 


at a new indentation level, four spaces or one tab stop. Give statements in a group the 
same indentation level, with procedure names and labels on a single line by themselves. 


An IF statement should be directly followed by the condition and the THEN keyword, 
with the next statement indented on the next line. When the IF statement has an 
associated ELSE, start the ELSE at the same level as the IF. Indent the statement 
following the ELSE and place it on the next line. For declarations, place the DECLARE 
keyword on a single line, followed by the declared elements indented on the following 
line. 


Avoid complicated attribute factoring because it reduces program readability. Insert 
blank lines when necessary to improve paragraphing and to separate logically distinct 
segments of the program. 


5.3. Abbreviations 


Many of the longer PL/I keywords have abbreviations (see the PL/I Command Sum- 
mary for a complete list). Inconsistent use of abbreviations decreases readability, so 
use either the long or short forms, but not both. Make use of the underscore in variable 
names to improve readability. 


5.4. Modular Format 


You should divide large programs into several logical groups, or modules, where 
each module performs a specific primitive function. You should make these modules 
PL/I subroutines that are either locally or externally defined. Local subroutines become 
a part of the same main program or subprogram, while you can separately compile 
and link together external subroutines. 


Place locally defined subroutines at the end of the program, so that the beginning 
contains only declarations and top-level statements that call the local subroutines. 
Neither the top-level statements nor the locally defined subroutines should exceed one 
or two pages in length. 


While learning to program in PL/I, use a main program, with locally defined sub- 
routines, following the form of the examples in this guide. When your application 
programs increase in size, however, you will find it more effective to break them into 
separate modules. This allows you to compile and link individual segments in pieces, 
thereby reducing overall development time. 
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5.5 Comments 


Comments should become an integral part of your program. They are an essential 
element in making your program readable, for yourself and other programmers. Avoid 
introducing random comments throughout the source file, and do not nest them. Con- 
sistency is the watchword. Place your comments at the beginning of subroutines or 
logical statement groups. If your program is properly structured into well-defined 
modules, these explanatory remarks provide the information required to understand 
the overall purpose and operation of your program. They also simplify the task of 
maintaining and updating the code without introducing errors. 


[ EKER EKER EE EHR EEK EER EKER EEE HERE ERE E RHEE HEHE / 
/* This program computes the largest of three */ 


/* FLOAT BINARY numbers x+ y+ and 2, */ 
[| ERE E KEE EERE EEK EEK EERE EHH ERK E EHH EEE HERE ERE E REESE / 
test: 
Procedure options(main) 
declare 
(arbroc) float binary$ 
Put list (‘Type Three Numbers: ‘)3 


get list (avboc)s 
Put list (‘The Largest Value is’ »smax3(asbec))3 


/* this procedure computes the largest of x» y+ and z *#/ 
max3: Procedure(xrysz) returns(float binary) 
declare 
(xeyezemax) float binarys 


if x > y then 


if x > z then 
I max = x$ 
else 


max = 23 
else 
if y > z then 
[ max = ¥§ 
else 
max = 23 
return(max)$ 
end max33 


L end tests 


Listing 5-1. PL/I Stylistic Conventions 
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Section 6 
Using the System 


Developing a PL/I program is a 3-step process: 


1. Write the source file using ED or a similar text editor. 

2. Compile the source file and generate the relocatable object file. 

3. Link the relocatable object file with the Run-time Subroutine Library to gen- 
erate an executable command file. 


9 UONIaS 


PL/I is a compiled language. Consequently, if you make any change to the source 
file, you must recompile the program. Try to divide large programs into several small 
modules, compile each module separately, then link them together. Small programs 
compile faster and use less storage for the Symbol Table. 


Figure 6-1 illustrates the development process. 
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Figure 6-1. PL/I Program Development 
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6.1 PL/I System Files 


When you receive your PL/I system you should first copy all of the files onto a back- 
up disk. If you are unsure how to do this, read your operating system documentation. 


Note: you have certain responsibilities when making copies of Digital Research pro- 
grams. Be sure you read your licensing agreement. 


After you make back-up disks, load your Compiler disk and type a DIR command: 
A>dir 
The directory contains several types of files, as shown in Table 6-1. 


Table 6-1. PL/I System Files 


Type Definition 


CMD Executable command file (8086 implementation), for example, 
DEMO.CMD 


Executable command file (8080 implementation), for example, 
DEMO.COM 


Default data filetype 


% INCLUDE file (data declarations) 


Indexed Relocatable File, for example PLILIB.IRL 


Relocatable object code file (8086 implementation), for example, 
DEMO.OBJ 


PL/I Compiler Overlays (8080 implementation), PLIO, PLI1, and PLI2 


PL/I Compiler Overlays (8086 implementation). PLIO, PLI1, and PLI2 
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Table 6-1. (continued) 


Type Definition 


PL/I source programs, for example, DEMO.PLI 


Printer disk file; compiled program listing on disk 


Relocatable object code file (8080 implementation), for example, 
DEMO.REL 


Symbol Table File, for example DEMO.SYM 


Note: the only files that contain printable characters are the PLI source programs the 
PRN printer listing files and the SYM Symbol table files. 
6.2 Invoking the Compiler 
Invoke the PL/I Compiler using a command of the general form: 
pli filespec [$s1...$s7] 


where filespec designates the program to compile and can include an optional drive 
specification. For example, 


d:myfile. pli 
You need not specify the filetype because the Compiler assumes type PLI. 
$s1...$s7 represent a list of parameters that you can optionally include in the com- 


mand line when compiling a program. These parameters are called switches, and they 
enable the various Compiler options as shown in Table 6-2 on the following page. 


In each case, the single-letter option follows the $ symbol in the command line. You 
can specify a maximum of seven options following the dollar sign. The default mode 
using no options compiles the program but produces no source listing and sends all 
error messages to the console. 
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Table 6-2. PL/I Compiler Options 


Option Action Enabled 


B Built-in subroutine trace. Shows the Run-time Subroutine Library 
functions that are called by your PL/I program. 


Disk file print. Sends the listing file to disk, using the filetype PRN. 


Interlist source and machine code. Decodes the machine language 
code produced by the Compiler in a pseudo-assembly language form. 


Kill parameter and %INCLUDE listings. Disables the listing of 
parameters and %INCLUDE statements during the Compiler’s first 
pass. 


List source program. Produces a listing of the source program with 
line numbers and machine code locations (automatically set by the 
I switch). 


Nesting level display. Enables a pass 1 trace that shows exact balance 
of DO, PROCEDURE, and BEGIN statements with their corre- 
sponding END statements. 


Object code off. Disables the output of relocatable object code nor- 
mally produced by the Compiler. 


Page mode print. Inserts form-feeds every 60 lines, and sends the 
listing to the printer. 


Symbol Table display. Shows the program variable names, along 
with their assigned, defaulted, and augmented attributes. 
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6.3 Compiler Operation 


The PL/I Compiler reads source program files and generates a relocatable, native 
code object file as output. PL/I is a 3-pass Compiler, with each pass a separate overlay. 
Pass 1 collects declarations, and builds a Symbol Table used by subsequent passes. 
Pass 2 processes executable statements, augments the Symbol Table, and generates 
intermediate language in tree-structure form. Both passes analyze the source text using 
recursive descent. 


Pass 3 performs the actual code generation, and includes a comprehensive code 
optimizer that processes the intermediate tree structures. Alternate forms of an equiv- 
alent expression are reduced to the same form, and expressions are rearranged to 
reduce the number of temporary variables. There is also a special-forms recognizer 
that detects and matches approximately three hundred tree structures of special interest. 
Special-forms recognition allows the Compiler to generate concise code sequences for 
many common statements. 


Note: all the Compiler overlays (PLIO, PLI1, and PLI2) must be on the default drive. 
As the Compiler proceeds through the first two passes, it displays the messages: 
NO ERROR(S) IN PASS 1 


NO ERROR(S) IN PASS 2 


If there are errors, the Compiler lists each line containing an error with the line number 
to the left, a short error message, and a ? below the position in the line where the error 
occurs. 


At the end Pass 3, the Compiler displays the message, 


CODE SIZE = nnnn 
DATA AREA = nnnn 
FREE SYMS = nnnn 
END COMPILATION 


where nnnn are hexadecimal numbers representing the amount of storage used for the 
code and data, as well as the amount of Transient Program Area (TPA) left for Symbol 
Table space. 
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Note: in the 8080 implementation, PL/I requires at least a 48K TPA. In the 8086 
implementation, PL/I requires an 96K TPA. 


If the number of error messages is excessive and you want to make corrections before 
proceeding, you can halt the compilation by typing a carriage return. The Compiler 
responds with the message: 


STOP PL/1 (Y/N)? 
Enter Y to halt the compilation. 


If you use the N switch, the Compiler lists the program line number on the left, 
followed by a letter a through z that denotes the nesting level for each line. The main 
program level is a, and each nested BEGIN advances the level by one letter, while each 
nested PROCEDURE advances the level by two letters. 


If you use the L switch, the Compiler lists the relative machine code address for each 
line as a four-digit hexadecimal number. This address is useful for determining the 
amount of machine code generated for each statement and the relative machine code 
address for each line of the program. The Compiler prints the source language statement 
on the line following the relative machine code value. 


Listings 6-1a and 6-1b show two compilations of a program called DEMO that is 
on your sample program disk. 


1a — demo: 

a 6 Procedure ortions(main) § 

3b 

4b declare 

2b name character(20) varyings 

Bib 

Rf 

8 b Put skip(2) list( ‘PLEASE ENTER YOUR FIRST NAME: ‘)3 
9b get list(name)s 

10 b Put skip(2) list( ‘HELLO ‘tinameit’» WELCOME TO PL/I ‘): 
11 6b 

12 b { end demo; 


Listing 6-1a. Compilation of DEMO Using $N Switch 


58 


PL/I Programming Guide 6.3 Compiler Operation 


1 a 0000 demo: 

2 a 0006 Procedure options(main)$ 

3 a 0006 

4 c 0006 declare 

5 c 0006 name character(20) varying 

6 c 0006 

7 c 0006 

8 c 0006 Put skip(2) list( ‘PLEASE ENTER YOUR FIRST NAME: ’ 
9 c 0022 get list(name)3 

10 c 003C Put skip(2) list(*‘HELLO ‘itinameiti’+s WELCOME TO PL/I ‘): 
11 c OOG6A 

12 a 


OO6A*-end demo; 


Listing 6-1b. Compilation of DEMO Using $L Switch 


6.4 The DEMO Program 


You can start learning to use the PL/I system by compiling the program called DEMO. 
The source file for DEMO is on your PL/I sample program disk, so you do not have 
to write the code. To display the source file, use the TYPE command, as follows: 


A>tyrpe demo.Pli 
To compile the DEMO program, enter the command: 
A>Pli demo 


Now examine your directory and find the object file that contains the relocatable 
machine code produced by the Compiler. The machine code produced by the Compiler 
is not directly executable, so you have to link the object file with the Run-time Sub- 
routine Library (RSL) with the command: 


A>link demo 


Now examine your directory and find the command file and the Symbol Table file 
produced by the linkage editor. You can load the Symbol Table file under SID™ or 
SID-86™ for debugging. 
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6.5 Running DEMO 
To run the compiled program, enter the name of the command file, 
A>demo 


The operating system loads the DEMO program, which begins processing and prompts 
you with the message, 


PLEASE ENTER YOUR FIRST NAME: 

Console input is free-field and incorporates the full line-editing facilities of the oper- 
ating system. When you enter your name, DEMO gives an appropriate response. Listing 
6-2 shows interaction with DEMO. 

A>demo 
PLEASE ENTER YOUR FIRST NAME: Larry 


HELLO Larrys WELCOME TO PL/I 
A> 


Listing 6-2. Interaction with the DEMO Program 


Various run-time errors can halt processing if the program does not explicitly inter- 
cept them. In this case, PL/I displays the message in the following form: 


error-condition (code), file-option, auxiliary-message 


Traceback: | aaaa bbbb cccc dddd # eeee ffff gggg hhhh 


The error-condition is one of the standard PL/I condition categories (see Section 4.4.4). 
Code is an error subcode identifying the origin of the error. 


PL/I prints the file option when the error involves an I/O operation, and takes the 
form, 


File: internal = external 
where internal is the internal program name that references the file involved in the 
error, and external is the external device or filename associated with the file. PL/I prints 


the auxiliary message whenever the preceding information is insufficient to identify the 
error. 
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The traceback portion lists up to eight elements of the internal stack. In the preceding 
general form, element aaaa corresponds to the top of the stack, while hhhh corresponds 
to the bottom of the stack. If the stack depth exceeds eight elements, the # character 
separates the four topmost elements on the left from the four lowermost elements on 


the right. 

Listing 6-3 is an example of the diagnostic form. In this case, the console input is 
an end-of-file (CTRL-Z) character. Entering a CTRL-Z signals the ENDFILE condition 
for the SYSIN file. This is standard console input. In this example, the external device 
connected to the SYSIN file is the console, denoted by CON. 

A>demo 

PLEASE ENTER YOUR FIRST NAME: *2 

END OF FILE (1)+ Files SYSIN=CON 

Traceback: O7BE 0769 012E 4000 # 0702 0322 8090 O012E 
A> 


Listing 6-3. Error Traceback for the DEMO Program 


6.6 Error Messages and Codes 


PL/I prints error messages and codes during compilation and while running the 
compiled program. During compilation, nonfatal errors are marked with an error 
message following the line in error, with a ? character near the position of the line in 
error. The ? might follow the actual error position by a few columns. One error on a 
line in some cases leads to additional errors. 


Fatal errors, marked with an asterisk in the following list, cause the Compiler to 
halt immediately. Run-time errors occur while the program is running. Although some 
run-time errors are fatal, most can be intercepted using ON statements. The Compiler 
errors are listed first. 
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6.6.1 General Errors 


DIR FULL* The operating system’s disk directory has overflowed. Erase unnec- 
essary files and try again. 


DISK FULL* All disk file space has been consumed. Erase unnecessary files and 
try again. 


INVALID INCLUDE A %INCLUDE statement is not properly formed. The 
% INCLUDE statement has the general form 


% include ‘d:filename.typ’; 
where d is the (optional) drive, and filename.typ is the file specification. 


LENGTH The item exceeds the maximum field width for the keyword or data item 
(31 characters for identifiers, 128 for strings). 


NO FILE x*_ The file x does not exist on disk. If x is of type PLI, then check to 
see that your source file is on the named disk. If the type is OVR, or OVL, then ensure 
that all three PL/I Compiler overlays (PLIO, PLI1, PLI2) are on the default disk. 


OUT OF MEMORY The memory size of the host system is too small. In the 8080 
implementation, PL/I requires at least a 48K Transient Program Area (TPA) for program 
compilation. In the 8086 implementation, PL/I requires a 96K TPA. 


READ ONLY x* The named file cannot be closed. Typically caused by disk that 
is set to Read-Only through hardware. 


TERMINATED.* Program error count exceeds 255, or terminated at the console 
by user typing return during the compilation process. 


TRUNC Line exceeds 120 characters in length and has been truncated. 


UNEXPECTED EQF* The end of the source program was encountered before the 
logical end of program. Typically due to unbalanced block levels (recompile with the 
$n toggle for nesting trace), or unbalanced comments and strings (check balance for 
missing */ or apostrophe characters). 


VALUE Indicates that the converted number exceeds the 16-bit capacity for FIXED 
BINARY constants (— 32768, +32767). 
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6.6.2 Pass 1 Errors 

BAD VAL The constant encountered in a format is invalid for this format item. 

BALANCE The parentheses for the expression are not balanced. 

BLOCK AT LINE x VARIABLE v EXCEEDS STORAGE The block begin- 
ning at source line x contains a variable v that caused the collective allocation of storage 


to exceed 65535 bytes. 


BLOCK OVERFLOW The nesting level of PROCEDURE, DO, and BEGIN blocks 
exceeds thirty-one levels. Simplify the program structure and try again. 


CONFLICT The attributes given in a declaration conflict with one another. 
DUPLIC The indicated variable is declared more than once within this block. 


LABEL The label for this statement is not properly formed. Only one label per 
statement is allowed, and subscripted label constants must have constant indexes. 


LENGTH The length of the indicated symbol exceeds the maximum symbol size. 
Simplify the structure and retry. Can also be caused by an unbalanced string. 


NESTED REP The %REPLACE statement is placed improperly in the block struc- 
ture. % REPLACE statements must occur at the outer block level before the occurrence 
of nested inner blocks. 


NO DCL: vi+ u2+ «++ vn The listed procedure parameters occurred in 
the procedure header, but were not declared within the procedure body. 


NOT BIF The BUILTIN attribute is applied to an identifier that is not a PL/I 
built-in function. 


NOT IMP The statement uses a feature that is not implemented in PL/I. 


NOT VARIABLE The declared name is treated as a variable, but does not have 
the VARIABLE attribute. 


NUMBER Numeric constant is required at this position in the format. 
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ON BODY Invalid statement occurs in the ON condition body. RETURN cannot 
be used to exit from an ON-unit. DO and IF require enclosing BEGIN...END block. 


PICTURE Picture declaration or P format item is improperly formed. 


RECUR PROC Recursive procedure contains invalid nested block. Only embedded 
DO-groups are allowed in recursive procedures. 


STRUCTURE The indicated structure is improperly formed. Nesting levels cannot 
exceed 255. 


SYMBOL LENGTH OVERFLOW* Maximum symbol size exceeded during con- 
struction of Symbol Table entry. Simplify and try again. 


SYMBOL TABLE QVERFLOW* This program cannot be compiled in the current 
memory size. Break the module into separate compilations, or increase the size of the 
TPA on your system. 


SYNTAX The specified statement is improperly formed. See the PL/I Language 
Reference Manual for proper statement formulation. 


6.6.3 Pass 2 Errors 


AGG VAL Actual parameter is an aggregate value that does not match the formal 
parameter. Change actual or formal parameter to match. 


ARG COUNT One of the following has occurred: subscript count does not match 
declaration; DEFINED reference to array element; more than 15 bound pairs; bound 
pairs do not match; or formal and actual parameter count does not match. 

BASE Invalid based variable reference. Occurs when pointer qualifier references 
nonbased variable, or variable is declared BASED(x), where x is not a simple pointer 
variable or simple pointer function call, as in BASED(P) or BASED(Q()). 

BASED REQ. A based variable is required in this context. 


BAD TYPE Control variable in iterative DO-group is invalid. Only scalar variables 
are allowed. 


BAD VALUE Invalid argument to built-in function. 
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BALANCE The parentheses for this expression are unbalanced. 


BIT CON Bit substring constant is out of range. The last argument to bit SUBSTR 
must be a constant in the range 1 to 16. 


BIT REQ A bit expression is required in this context. 


CLOSURE The label following the END does not match the preceding correspond- 
ing PROCEDURE name. 


COMP REQ A noncomputational expression has been used where a computational 
expression is required. 


COMPILER ERROR A compiler error has occurred. The error might be due to 
previous errors. 


CONFLICT Data attributes are in conflict, or attributes in OPEN statement are 
not compatible. 


CONVERT Cannot convert the constant to the required type. 


EXPRESSION QVERFLOW* The expression has overflowed the Compiler’s internal 
structures. Simplify and try again. 


ID REQ An identifier is required in this context. 

INT REQ An integer (FIXED BINARY) expression is required in this context. 
LABEL Improperly formed label encountered where label expected. 

NO BUILTIN Referenced built-in function not implemented in PL/I. 

NO DCL Indicated variable has not been declared in the scope of this reference. 
NOT FILE The reference within a FILE option is not a file variable or file constant. 


NOT FORMAT The format field of a GET or PUT EDIT does not reference a 
format. 


NOT IMP The construct in this statement is not implemented in PL/I. 
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NOT KEY The expression within a KEYTO, KEYFROM, or KEY option is not a 
FIXED BINARY variable. 
NOT LABEL The target of this GOTO statement is not a label value. 


NOT PROC The reference following a CALL is not a procedure value. 


NOT SCALAR A nonscalar value was encountered in a context requiring a scalar 
expression. 


NOT STATIC. An attempt was made to initialize automatic storage. Declare with 
STATIC attribute and retry. 


PTR REQ. A pointer variable is required in this context. 


QUALIFY This reference to a structure does not properly qualify the variable 
name; usually due to nonunique substructure reference. 


RET EXP The expression in a return statement is not compatible with the RETURNS 
attribute of the corresponding procedure. 


RETURN An attempt to return value from procedure was made without RETURNS 
attribute. 


SYNTAX Statement is improperly formed. See PL/I Language Reference Manual 
for proper statement formulation. 


SCALE GREATER THAN ©. The resulting FIXED BINARY expression produces 
a nonzero scale factor. If the expression involved division, replace x/y by DIVIDE(x,y,0). 
This is necessary to maintain full language compatibility. 


SYMBOL TABLE QVERFLOW* Free memory space exhausted during compila- 
tion. (See similar error in Pass 1.) 


STR REQ A string variable is required in this context. In the case of the SUBSTR 
built-in function, assign the expression to a temporary variable before the substring 
operation takes place. 


TYPES NOT= The types of a binary operation are not compatible. Check dec- 


larations and conversion rules. Might be due to aggregate data items that do not match 
in structure. 
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UNSPEC Source or target of UNSPEC operation is not an 8- or 16-bit variable. 


# VALUES The number of items specified in an INITIAL statement is not com- 
patible with the variable being initialized. 


YAR REQ. A variable is required in this context. 


6.6.4. Pass 3 Errors 


**¥* AUTOMATIC STORAGE OVERFLOW*** The total storage defined within 
this program module exceeds 65535 bytes. 


BAD INT FILE The intermediate file sent to Pass 3 is invalid, and is usually due 
to a hardware malfunction. 


BLOCK OVERFLOW Nesting level has exceeded the Compiler’s internal tables 
(maximum 32 levels). 


EOF ON INT FILE Premature end-of-file encountered while reading interme- 
diate file. Usually due to hardware failure. 


EXPRESSION QVERFLOW* The Compiler’s internal structure sizes have been 
exceeded. Simplify expression and retry. 


LINE x OPERATION NOT IMPLEMENTED An invalid intermediate opera- 
tion has occurred. Usually due to hardware failure or errors in a previous pass. 


6.6.5 Run-time Errors 


Run-time errors occur when the linked program is loaded and executed. Run-time 
errors are divided into two categories: fatal errors, which stop execution, and nonfatal 
errors, which can be intercepted with ON-units. 


6.6.6 Fatal Run-time Errors 


FREE REQUEST OUT OF RANGE A FREE statement specifies a storage address 
outside the range of the free storage area, and is usually caused by reference to an 
uninitialized base pointer. 
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FREE SPACE OVERWRITE The free storage area has been destroyed, and is 
usually caused by an out-of-range subscript reference or a stack overflow. If stack 
overflow occurs, use the STACK(n) keyword in the OPTIONS field to increase the 
stack size. 


INSUFFICIENT MEMORY The loaded program cannot execute in the memory 
size allocated to the transient program. If possible, increase the size of the Transient 
Program Area. 


INVALID I/O LIST The list of active files has been destroyed during execu- 
tion, and the attempt to close all active files at the end of execution failed. Usually due 
to subscript values out-of-range. 


6.6.7 Nonfatal Errors 


The following errors are printed when no ON-unit is active, or if control returns 
from an ON-unit corresponding to a fatal condition (marked by an asterisk). In each 
case, the condition prefix is listed, followed by an optional subcode that identifies the 
error source, followed in some cases by an auxiliary message that further identifies the 
source of the error. 


ERROR(1) "“Conversion"* Occurs whenever conversion cannot be per- 
formed between data types, and might be signaled during arithmetic operations, assign- 
ments, and I/O processing with GET and PUT statements. 


ERROR(2) "I/O Stack OQverflow"* The run-time VO stack has exceeded 
16 simultaneous nested I/O operations. Simplify the source program and try again. 


ERROR(3)* Transcendental function argument is out-of-range. 


ERROR(4) "I/O Conflict x"* A file has been explicitly or implicitly opened 
with one set of attributes, and subsequently accessed with a statement requiring con- 
flicting attributes. The value of x is one of the following: 


@ STREAM/RECORD 
@ SEQUEN/DIRECT 
@ INPUT/OUTPUT 

@ KEYED Access 


The first conflict arises when ASCII files are processed using READ or WRITE, but 
the INTO or FROM option does not specify a varying character string. 
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ERROR(S) “Format Overflow"* The nesting level of embedded formats 
has exceeded 32. Simplify the program and try again. 


ERROR(6) “Invalid Format Item"* The format processor has encoun- 
tered a format item that cannot be processed. The P format is not implemented in 
PL/I. 


ERROR(7) "Free Space Exhausted"* No more free space is available. 
If intercepted by an ON-unit, do not execute ALLOCATE, OPEN, or recursion without 
first releasing storage. 


ERROR(8) “OQVERLAY» NO FILE d:filename" The indicated file could 
not be found. 


ERROR(9) “OVERLAY: DRIVE d:filename" An invalid drive code was 
passed as a parameter to overlay. 


ERROR(10) “OVERLAY+ SIZE d:filename" The indicated overlay will 
overwrite the PL/I stack and/or free space if loaded. 


ERROR(1i1) "“OQVERLAY» NESTING d:filename" Loading the _ indi- 
cated overlay would exceed the maximum nesting depth. 


ERROR(12) "“OQVERLAY+s READ d:filename" Disk read error during 
overlay load; probably caused by premature EOF. 


ERROR(13) “Invalid OS Version" Caused by any operation that gen- 
erates an operating system call not supported under the current operating system. 


ERROR(14) “Unsuccessful Write" Caused by any unsuccessful write 
operation on a file due to lack of directory space, lack of disk space, etc. 


ERROR(15) “File Not Geen" Caused by any attempt to lock or unlock a 
record in a file that is not open. 


ERROR(1G) “File Not Keyed" Caused by any attempt to lock or unlock 
a record in a file that does not have the KEYED attribute. 


FIXEDOVERFLOW A decimal add or multiply produced a value exceeding 15 
decimal digits of precision, or an attempt was made to store to a variable with insuf- 
ficient precision. 
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OVERFLOW(1) A floating-point operation produced a value too large to be rep- 
resented in floating-point format. 


OVERFLOW(2) A double-precision floating-point value has been assigned to a 
single-precision value with insufficient precision. 


UNDERFLOW(1) A floating-point operation produced a value too small to be 
represented in floating-point format. 


UNDERFLOW(2) A double-precision floating-point value has been assigned to a 
single-precision value with insufficient precision. 


ZERODIVIDE(1) A decimal divide or modulus operation was attempted with a 
divisor of zero. 


ZERODIVIDE(2) A floating-point divide or modulus operation was attempted 
with a divisor of zero. 


ZERODIVIDE(3) An integer divide or modulus operation was attempted with 
a divisor of zero. 


ENDFILE An attempt was made to read past the end of the listed file, or the disk 
full condition occurred during output. 


UNDEFINEDFILE The named file cannot be found on the disk if input, or cannot 
be created if output. Also occurs when an input device is opened for output, or an 
output device is opened for input. 

KEY (1) Invalid key detected in output operation. 


KEY(2) Invalid key encountered during input operation. 


ENDPAGE An end-of-page condition was detected. This condition does not cause 
termination if no ON-unit is active. 


End of Section 6 


Section 7 
Using Different Data Types 


PL/I programs allow you to use different data types to suit different applications. In 
programs throughout the manual, you should note how and why each type of data is 
used in a particular situation. 


7.1 The FLTPOLY Program 


Listing 7-1 shows a program for evaluating a polynomial expression. The program 
begins by reading three values, x, y, and z, from the console, and then uses the values 
to evaluate the polynomial expression: 


P(xX#y¥9z) = x2 4 2y +2 


The main part of the program is bounded by a single DO-group. On each successive 
iteration, the program reads the values of x, y, and z from the standard SYSIN, console, 
file. The program then writes the value produced by p(x,y,z) to the SYSPRINT file, 
again, the console file. Finally, if all the input values are zero, the program executes 
the STOP statement and ends the indefinite loop. 


The program uses the % REPLACE statement on line 8 to define the literal value of 
true as the bit-string constant, ‘1’b. The Compiler substitutes this value whenever it 
encounters the name true. Thus, the Compiler interprets the DO-group beginning on 
line 13 as, 


do while(‘1’b)3 


* 


ends 


which loops until it executes the contained STOP statement. Using % REPLACE state- 
ments to define constants can improve the readability of your programs. 
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[HEHEHE EK KEKE E ERE EERE EE EE EERE RE REE RE / 
/* This program evaluates a polynomial expression */ 


/* using FLOAT BINARY data. */ 
[| EERE HERI EERIE EEE EERE EEE HEE EER EEE / 


fitroly: 
Procedure ortions(main)3 


oOnNOWRPUN re 


“replace 
true by ‘1’b3 
declare 
(xeyez) float binary(24)3 


do while(true)3 
Put skip(2) list( ‘Tyre x+syvoezs 
Set list(xsyvez)3 


if x=0 & y=0 & z=0 then 
SLOP 


Put skip 2h 
Put skip x + 2y + Zz = oP(KXevez)dS 
end3 


Ps 
Procedure (x+vy#z) returns (float binary(24))$ 
declare 
(xevyez) float binary 
return Uk # e412 # y+ 279 
end P3 


a 
a 
a 
a 
a 
b 
b 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
b 
b 
c 
c 
c 
c 
c 
b 
b 


end fltroly3s 


Listing 7-1. Polynomial Evaluation Program (FLOAT BINARY) 
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Listing 7-2 shows the console interaction with the FLTPOLY program. The initial 


values for x, y, and z are: 1.4, 2.3, and 5.67, but on the next loop, the input takes the 
form: 


+4 ra) ae 
This form changes the value of y only. Thus, on this loop, the values of x, y, and z 


are 1.4, 4.5, and 5.67. The third input line changes y and z, while the fourth line 
changes x only. 


A>fltroly 
Type xeyez: 164+ 2.3% 5.67 


2 
x + 2y +z = 1,223000E+01 


Type xXeyezs 46 GiSae 


2 
x + 2y + 2 = 1,663000E+01 


Type xX+¥ez? » +Be-3+ 7 


2 
x + 2y +2 = 0,896119E+01 


Type Xevezs 2eBroe 


2 
x + 2y +2 = 1,229119E+01 


Type xrvexe 01090 


A> 


Listing 7-2. Interaction with FLTPOLY Program 
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7.2 The DECPOLY Program 


Listing 7-3 shows the DECPOLY program, which is essentially the same program 
as Listing 7-1. The difference between the two programs is that FLTPOLY uses FLOAT 
BINARY data items, while DECPOLY uses FIXED DECIMAL items. FLOAT BINARY 
computations execute significantly faster than their FIXED DECIMAL equivalents, but 
single-precision FLOAT BINARY computations involve truncation errors, and produce 
an answer with only about 7 decimal places of accuracy. 


ia JL HHH HK HHH EEE EEE EEE EEE HHH EEK HEHEHE EEE EE REE / 
Za /* This program evaluates a Polynomial expression */ 
3a /* using FIXED DECIMAL data, */ 
Ae [HHH HHH HEHEHE EEE KEE EERE EEE HHH HEHE EEE EH EERE EERE EEE / 
S a-decpoly: 

6 b Procedure options(main)3 

7b 

8 b “replace 

9b true by ‘1‘bi 

10 b declare 

11 6b (xeyez) fixed decimal (15+4)3 

12 b 

i3c y— do while(true)s 

14d c¢ Put skip(2) list( ‘Type xeyezs ‘)5 

15 ¢ Set list(xsyez)5 

16 c 

7c if x=0 & y=0 & z=0 then 

18° 0 stop; 

19 6 
20 ¢ Put skip list(* fae 
21-8 Put skip list(‘ K + 2¥ +z =’ oP(xevez))5 
22 ¢ — ends 
23 b 
24 b P's 
25 °t Procedure (x+y+z) returns (fixed decimal(1514))35 
26 c declare 
pa ae (xeyez) fixed decimal (15+4)3$ 
26 6c returh (4 2 + 2. ey + 205 
Zoe end P3 
30 b 
31 bend decpolys 


Listing 7-3. Polynomial Evaluation Program (FIXED DECIMAL) 
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Listing 7-4 shows the console interaction with the DECPOLY program. The initial 
input values for x, y, and z are: 1.4, 2.3, and 5.67. These are the same values used for 
the FLTPOLY program, but notice the difference in the output. The second loop changes 
the values of y and z, and the third loop changes all three values. 


A>decroly 
Type xevez: 14649 2.3% 5.67 


2 
Me Se 2 Foz 12.2300 


Type xsyez: + +0006% 7 


2 
x 2y +z = 


Type xeyez: 723.4451 80.541 0 


2 
x + 923533.7480 


Type Xeyveze 


A> 


Listing 7-4. Interaction with DECPOLY Program 


Experiment with these two programs by comparing the results when you enter the 
same values in each one. Then read Section 17, which describes the internal data 
representation for all PL/I data types. Understanding how PL/I internally treats the 
different data types helps you choose the right type of data to suit the application. 


End of Section 7 


References: Section 3.1 LRM 
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Section 8 
STREAM and RECORD File 
Processing 


The example programs in this section illustrate STREAM and RECORD file process- 
ing using the various I/O statements. 


8.1 File Copy Program 


Listing 8-1 shows a general purpose, file-to-file copy program. The program first 
defines and opens two file constants called input_file and output_file. It then begins 
executing a continuous loop that reads data from input_file and copies it to output_file. 


Both OPEN statements define STREAM files with internal buffers of 8192 characters 
each. In the first OPEN statement, PL/I supplies the default attribute INPUT, while the 
second OPEN statement explicitly specifies an OUTPUT file. Otherwise, it would also 
default to an INPUT file. 


This program shows the special use of READ and WRITE statements to process 
STREAM files. The READ statement on line 19 reads a STREAM file into buff, a 
character string of varying length. It reads each line of input up to and including the 
next carriage return line-feed into buff, and sets the length of buff to the amount of 
data read, including the carriage return line-feed character. The WRITE statement 
performs the opposite action. It sends the data to a STREAM file from buff. The output 
file receives all characters from the first position through the length of buff. 


The program terminates by reading through the input file until it reaches the end- 
of-file (CTRL-Z) character. PL/I automatically closes all open files, and writes the 
internal buffers onto the disk, thus preserving the newly created output file. 
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er [EERE R EEE E EEE KEE EEE HEE HEH ERE EEE / 
2a /* This Program copies one file to another using */ 
3a /* buffered I/O. */ 
Ga [HHH EHH RHE HIRE EEE HH EEE EEE KEE EERE EERE EERE HEH / 
Sa copy: 

6 b Procedure options(main) 3 

7b declare 

8b (input _filerouteput file) files 

9b 

10 b open file (input file) stream 

11 b environment(b(8192)) title(‘$1,$1/)$ 

12 b 

13 b open file (output file) stream outPut 

14 b environment(b(8192)) title(‘$2.$2')3 

15 b declare 

16 b buff character(254) varvying3 

178 

18 c do while(‘1’b)3 ; 
19 c tread file (input _file) into (buff)i 
20 c write file (output file) from (buff)3 

2ic endi 

22 blend copy; 


Listing 8-1. COPY (File-to-File) Program 


Listing 8-2 shows a sample execution of the copy program using the following 
command line: 


A>coPy copy,Pli $¢con 


In this case, the input file is COPY.PLI, the original source file, while the output file 
is the system console. Thus, the program simply lists COPY.PLI at the terminal. 


The TITLE options connect the internal filenames to external devices and files. The 
command line has two parts: the command itself, and the command tail, which can 


contain two filenames. 
Command ee 
a $1 $2 
copy-pli 


Figure 8-1. Default Filenames in the Command Tail 
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8.1 File Copy Program 


The OPEN statement on line 10 takes the first default name, including the drive in 
the command tail (denoted by $1.$1), and assigns it to the internal file constant called 
input_file. Similarly, the second OPEN statement on line 13 takes the second default 
name including the drive in the command tail (denoted by $2.$2), and assigns it to 
the internal file constant called output_file. 


For example, the command, 


A>coPy arzx.dat crusnew 


copies the file X.DAT from drive a to the new file UNNEW on drive c. The input file 


must exist, but PL/I erases the output file if it exists, and recreates it. 


A>corPy corpy.Pli $con 


la 


a 
a 
a 
a 
b 
b 
b 
b 
b 
b 

12 6 
b 
b 
b 
b 
b 
c 
c 
c 
c 
b 


[HHH EH EK EEK EEK EH EEE HEHEHE EEE EE EEK EEE HE EERE EEE / 
/* This program copies one file to another using */ 


/* buffered I/O, #/ 
[ERK EHE EERE HEE EE EEE EH EEE HERE ERE KEKE EEE HERES / 
COPY: 

Procedure options(main)$ 

declare 


(input _fileroutput file) filei 


open file (input file) stream 
environment(b(8192)) title(‘$1.$1')5 


open file (output file) stream output 
environment(b(8192)) title(‘$2.$2')35 
declare 
buff character(254) varying; 


do while(‘i’b)i 
read file (input_file) into (buff)3 
write file (output file) from (buff)i 
ends 
end copy$ 


END OF FILE (3) File: INPUT=COPY.PLI 
Traceback : O44B O3AF 0155 


A> 


Listing 8-2. Interaction with the COPY Program 
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8.2 Name and Address File 


The two programs in Listings 8-3 and 8-6 manage a simple name and address file. 
The CREATE program produces a STREAM file containing individual names and 
addresses that are subsequently accessed by the RETRIEVE program. 


8.2.1 The CREATE Program 


The CREATE program in Listing 8-3 contains a data structure that defines the name, 
address, city, state, zip code, and phone number format. This data structure is not in 
the source file CREATE.PLI. It is contained in a separate file named RECORD.DCL, 
and CREATE uses an %INCLUDE statement to read and merge this file with the source 
file. Both files are on your sample program disk. The + symbols to the right of the 
source line number in the listing indicate that the code comes from an %INCLUDE 
file. The actual line in the source program appears as follows: 


create: 
Procedure options(main)3 


Zinclude ‘record.del’s 


The file specified in the %INCLUDE statement can be any valid filename. The Compiler 
simply copies the file at the point of the %INCLUDE statement, and then continues. 


The OPEN statement, line 29, does not specify the PRINT attribute. This means the 
output file is in a form suitable for later input using a GET LIST statement. 


[EERE ERE KER EE EE EEK EE HERE KEE EKER KER H ERE REE EERE EHRHEE/ 
/* This Program creates a name and address file. The */ 
/* data structure for each record is in the ZINCLUDE #*/ 
/* file RECORD.DCL. */ 


[RHEE RHEE RHE EERE HEHEHE HEHEHE EHH EE HE EHR EHR H RE HERR E ERR ERE RHEE / 


create: 
j Procedure orptions(main) 3 


aor oownneauwudne 
oro To wownwp wp 


Listing 8-3. CREATE Program 
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declare 
1 record, 

2 name character(30) varying, 
addr character(30) varying», 
city character(20) varying: 
state character(10) varying» 
zip fixed decimal(6), 
Phone character(12) varving3 

“replace 
true by ‘1i’b» 
false by ‘O’b3 


declare 
output file» 
filename character(14) varying» 
eofile bit(1!) static initial(false)$ 


Put list (‘Name and Address Creation Program» File Name: ‘)3 
get list (filename); 


open file(output) stream output title(filename)§ 


do while (*eofile)s 

Put skip(3) list( ‘Name: 

get list(name)3 

eofile = (name = ‘EOF’) 

if “eofile then 

doj 

/* write Prompt strings to console #*/ 
Put list(‘Address: ‘)3 
get list(addr)$ 
Put list(‘City» State» Zip: ‘)§ 
get list(city» state» zip)i 
Put list(‘Phone: ‘)3 
get list(Phone)3 


/* data in memory» write to output file #/ 
Put file(output) 
list(namesaddrecitysstaterzip+Phone)$ 
Put file(output) skip§ 
end§ 

end3 

Put file(output) skip list(‘EOF’)$ 

Put file(output) skip3 


end create 


Listing 8-3. (continued) 
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Listing 8-4 shows the console interaction with the CREATE program. You specify the 
output file as names.dat in the first input line. The GET LIST statement, line 33, accepts 
input delimited by blanks and commas, unless the delimiters are included in single 
apostrophes. Thus, CREATE takes the input line, 


‘John Robinson 


as a single string value with PL/I automatically inserting the implied closing apostrophe 
at the end of the line. The last entry includes the three input values, 


Unknowns ‘Can’’t Find’, 99999 


that CREATE assigns to the variables city, street, and state. Because the first value 
does not begin with an apostrophe, the I/O system scans the data item until the next 
blank, tab, comma, or end-of-line occurs. The second data item begins with an apos- 
trophe, and this causes the I/O system to consume all input through the trailing balanced 
apostrophe, and reduce all embedded double apostrophes to a single apostrophe. The 
last value, 99999, is assigned to a decimal number, and must contain only numeric 
data. 


You can use the command, 
A>tyPe names.dat 


to display the STREAM file that the program creates. Listing 8-5 shows the output 
resulting from each input entry. 


A>dcreate 
Name and Address Creation Program» File Name: names.dat 


Name: ‘Arthur Jackson’ 

Address: ‘100 W, 3rd St.’ 

City» State» Zip: ‘Fresno’s ‘Ca.’s 93706 
Phone: ‘529-1277’ 


Name: ‘Donna Harris’ 

Address: ‘2999 Serra Rd,’ 

City, States Zip: ‘Chico’s ‘Ca,’» 95926 
Phone: ‘635-3570’ 


Listing 8-4. Interaction with the CREATE Program 
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Name: ‘John Robinson 

Address: ‘805 Franklin St.’ 

City, State, Zip: ‘Monterey’s ‘Ca.’s 93940 
Phone: ‘649-1000’ 


Name: ‘Virginia Wilson’ 

Address: wee 

City» State» Zip: Unknowns ‘Can’’t Find’, 99999 
Phone: '‘?’ 


Listing 8-4. (continued) 


A>tyPe names.dat 

‘Arthur Jackson’ ‘100 W. 3rd St.’ ‘Fresno’ ‘Ca.’ 93706 ‘529-1277’ 
‘Donna Harris’ ‘2999 Serra Rd.’ ‘Chico’ ‘Ca.’ 95926 ‘635-3570’ 

‘John Robinson’ ‘805 Franklin St.’ ‘Monterey’ ‘Ca.’ 93940 ‘649-1000’ 
‘Virginia Wilson’ ‘?’ ‘Unknown’ ‘Can’’t Find’ 99999 ‘?’ 


‘EOF’ 
A> 


Listing 8-5. Output from the CREATE Program 


8.2.2 The RETRIEVE Program 


The RETRIEVE program shown in Listing 8-6 reads the file created by CREATE, 
and displays the name and address data upon user request. The Compiler includes the 
same RECORD.DCL file used in the CREATE program, shown in Listing 8-3. 


The main DO-group in the RETRIEVE program, between lines 30 and 59, reads 
two string values corresponding to the lowest and highest names to print on each 
iteration. The embedded DO-group between lines 41 and 57 reads the entire input file 
and lists only those names between the lower and upper bounds. 


The RETRIEVE program, similar to the CREATE program, reads the name of the 
source file from the console. However, RETRIEVE opens and closes this source file 
each time it receives a retrieval request from the console. 
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The OPEN statement on line 38 sets the internal buffer size of the input file to 1024 
bytes. After processing the file, RETRIEVE executes the CLOSE statement on line 58 
and flushes all internal buffers. Thus, RETRIEVE sets the input file back to the beginning 
on each retrieval request. 


HR RT ETE EE TEE TEE TETHER EH EEE EE EEE EE / 
/* This program reads a name and address data file #*/ 
/* and displays the information on request, */ 
[HERR IH K HE ERR RE HEE EEE HEHE EEE EERE HEHEHE / 
retrieve: 

Procedure oPtions(main)$ 


declare 
1 records 
2 name character(30) varying» 
addr character(30) varying» 
city character(20) varying» 
State character(10) varying» 
zip fixed decimal(6),» 
Phone character(12) varying 
“replace 
true by ‘1’b»s 
false by ‘O’b$ 


declare 
(sysprints input) file» 
filename character(14) varying» 
(lowers upper) character(30) varying» 
eofile bit(1)3 


open file(sysprint) Print title('$con’)$ 
Put list(‘Name and Address Retrieval: File Name: ‘)3 
get list(filename)3 


do while(true)3 
lower = ‘AAARAAAARAAARAAAARAAARAAAAAAAA’ § 
upper = ‘222222222222222222222222222222/3 
Put skip(2) list(‘Type Lowers Upper Bounds: ‘)$ 
get list(lowersupper) 3 
if lower = ‘EOF’ then 
StOP3 


b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
c 
c 
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38 ¢ open file(input) stream input environment(b(1024)) 
39 ¢ title(filename)$ 

40 ¢ eofile = false 

4id do while (*eofile)s 

42 4d get file(input) list(name)3 

43 d eofile = (name = ‘EOF’)3$ 

44d if “eofile then 

45 e — dos 

46 e get file(input) 

a7 e list(addrscitysstaterzipsPhone) 3 
48 e if name >= lower & name <= upper then 
4g f dos 

50 f Put Page skip(3)list(name)j 
51 f Put skip list(addr)$ 

52 f Put skip list(citysstate)§ 
= Put skip list(zip)3 

54 f Put skip list(Phone)3 

oT endi 

56 e ends 

57 d end 

58 ¢ close file(inrut)s 

59 c L_ endi 

60 b 

61 b end retrieve} 


Listing 8-6. (continued) 


Listing 8-7 shows user interaction with the RETRIEVE program. Again, the input 
file is names.dat, and exists on the disk in the form produced by CREATE. The input 
values, 


BoE 


set lower to B and upper to E and cause RETRIEVE to list only Donna Harris. The 
second console input line sets lower to B and upper to K. This causes RETRIEVE to 
list Donna Harris and John Robinson. The comma in the next input value sets the 
lower bound at AAA...A and the upper bound as K. Thus RETRIEVE lists Arthur 
Jackson, Donna Harris, and John Robinson. The last entry consists only of a comma 
pair, leaving the lower bound as the sequence AAA...A and the upper bound at zzz...z. 
These two bounds include the entire alphabetic range, so that RETRIEVE displays the 
entire list of names and addresses. Finally, entering EOF ends the program. 


Line 26 of Listing 8-6 opens the SYSPRINT file with the PRINT attribute and title 
of $CON. It is good programming practice to open all files with explicit attributes. In 
this case the statement is redundant because when PL/I executes the PUT LIST statement 
on line 27, it supplies the same attributes to the file by default. 
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A>retrieve 
Name and Address Retrieval, File Name: 


Type Lower» Upper Bounds: 6+E 


Donna Harris 
2999 Serra Rd, 
Chico Ca, 
95926 
635-3570 


Type Lowers Upper Bounds: Brk 


Donna Harris 
2999 Serra Rd. 
Chico Ca, 
95926 
635-3570 


John Robinson 
805 Franklin St. 
Monterey Ca. 
93940 
649-1000 


Type Lowers Upper Bounds: +k 


Arthur Jackson 
100 W. 3rd St. 
Fresno Ca. 
93706 
529-1277 


Donna Harris 
2999 Serra Rd. 
Chico Ca, 
95926 
635-3570 


names,dat 
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John Robinson 
805 Franklin St. 
Monterey Ca, 
93940 
649-1000 


Type Lowers Upper Bounds: +» 


Arthur Jackson 
100 W. 3rd Sts 
Fresno Ca. 
93706 
529-1277 


Donna Harris 
2999 Serra Rd. 
Chico Ca. 
95926 
635-3570 


John Robinson 
805 Franklin St. 
Monterey Ca, 
93940 
649-1000 


Virginia Wilson 
2 


Unknown Can’t Find 


99999 
Ed 


Type Lowers Upper Bounds: EOF yr» 


A> 


Listing 8-7. 
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8.3 An Information management System 


The next four sample programs provide a model for an information management 
system. These programs manage a file of employee names, addresses, wage schedules, 
and wage reporting mechanisms. Each of these programs is simple, but together they 
contain all the elements of a more advanced data base management system. They 
demonstrate the power of the PL/I programming system, while providing the basis for 
custom application programs. 


First, the ENTER program establishes the data base. A second program, called 
KEYFILE, reads this data base and prepares a key file for direct access to individual 
records in the data base. A third program, called UPDATE, interacts with the user at 
the console and allows access to the data base for retrieval and update. Finally, the 
REPORT program reads the data base to produce a report. 


8.3.1 The ENTER Program 


Listing 8-8 shows the ENTER program. The ENTER program interacts with the 
user at the console and constructs the initial data base. The basic input loop between 
lines 40 and 53 prompts the user for an employee name, age, and hourly wage. ENTER 
fills the employee data structure with this information. In the example, line 48 fills the 
address fields with default values defined in the structure on lines 24 through 33. You 
can terminate the console input by entering EOF. 


The employee record contains several fields whose total length is 101 bytes. You 
can use the $S Compiler switch to verify this value. The OPEN statement on line 37 
specifies a fixed record size of 128 bytes, so you can expand the records later. Each 
record of the emp file holds exactly one employee data structure. 


The OPEN statement gives emp the KEYED attribute, and makes each record the 
fixed size specified in the ENVIRONMENT option. The OPEN statement also specifies 
the buffer size as 8000 bytes, which PL/I automatically rounds off to 8192 bytes. The 
program fills each employee record from the console input and writes the record to 
the employee file named in the command line, with the file type EMP, line 38. 


The WRITE statement is in a separate subroutine, named WRITE-IT, starting on line 
55. Placing the code in a separate subroutine helps reduce the size of the program because 
the program calls WRITE-IT at two different points, lines 45 and 52. 
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Listing 8-9 shows the user interaction with the ENTER program as several employee 
records are entered. Entering EOF ends the program, closes the file plantl.emp, and 
records the data on the disk. 


[ EEK EEEK EE EE EERE EHEE EERE EE EERE REE RHEE HERE E EERE EE REEE/ 
/* This program constructs a data base of employee #/ 


/* records using a structure declaration, */ 
| HEH HH EK KEE HEE HERE HREE HEE EEE EE EEK EEE EEE EEE EE EEE / 


enter: 
Procedure orptions(main)$§ 
Zreplace 
true by ‘1’bs 
false by ‘O’b3 


declare 
1 employee static» 

2 name character(30) varying» 

2 address» 
3 street character(30) varying» 
3 city character(10) varying» 
3 state character(12) varying» 
3 zip fixed decimal(5)» 
age fixed decimal(3)» 
wage fixed decimal(512),5 
hours fixed decimal(551)5 


declare 
1 default static» 
2 street character(30) varying 
initial(‘(no street)’)» 
2 o1ty character(10) varying 
initial(‘(no city)’)» 
2 state character(12) varying 
initial(‘(no state)’)» 
2 zip fixed decimal(5S) 
initial (00000)3 
declare 
emp files 


open file(emp) Keyed output environment(f(128) +b(8000)) 
title (‘$1,EMP‘)3§ 
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do while(true); 
Put list( ‘Employee: ‘)3$ 
get list(name)3 
if name = ‘EOF’ then 
dos 
call write it()i 
StOP3 
end; 
address = defaults 
Put list (* Agey Wage: ‘)3 
get list (agyerswage)§ 
hours = 03§ 
call write it()i 
end 


write it: 

Procedures 

write file(emp) from(emplovee)$ 
end write iti 


“end enter; 


Listing 8-8. (continued) 


A>enter Plant! 
Employee: Jackson 

Age, Wage: 25+ 6.75 
Employee: Harris 

Ase, Wage: 30, 9,00 
Employee: Robinson 

Age, Wage: 41+ 15.00 
Employee: Wilson 

Age» Wage: 27% 7,50 
Employee: Smith 

Age, Wage: 25, 
Employee: Jones 

Age, Wage: ae 
Employee: EOF 
A> 


Listing 8-9. Interaction with the ENTER Program 
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8.3.2 The KEYFILE Program 


Listing 8-10 shows the KEYFILE program, which constructs a key file by reading 
the data base file created by ENTER. The key file is a sequence of entries consisting 
of an employee name followed by the key number corresponding to that name. In this 
case, the key file is also a STREAM file, so you can display it at the console. Line 16 
opens the $1.EMP file with the KEYED attribute, specifies each record to be 128 bytes 
long, and sets a buffer size of 10000 bytes. Line 19 opens the key file named keys as 
a STREAM file with LINESIZE(60) and a TITLE option that appends KEY as the 
filetype. 


On line 23, the KEYFILE program reads successive records, extracts the key with 
the KEYTO option, and writes the name and key to both the console and to the key 
file. The sample interaction in Listing 8-11 illustrates the output from KEYFILE using 
the plantl.emp data base. Each key value extracted by the READ statement is the 
relative record number corresponding to the position of the record in the file. 


After executing the KEYFILE program, you can use the command 


A>type Plantl,.Key 


to display the actual contents of the plant1.key file as shown in Listing 8-12. 


[HK KR KE IE EE EERIE ETE ETE EGET EEE / 
/* This Program reads an employee record file and */ 


/* creates another file of Keys to access the records, */ 
[ EEK EEEKE KEE EEE EEE EERE HERE HEE EEE ER ERE ERE E KERR RRR EKER HEHE / 


—kevyfile: 
Procedure options(main)3 
declare 
1 employee static» 
2 name character(30) varying 


declare 
(input, Keys) file» 
kK fixeds 


open file(input) kKeved environment (f(128) »b(10000)) 
title(‘$l.,emp’)§ 


ee 
OOWOnN OAM BDWYANK OCOHWONYNDUWSWN YK 


open file(kKeys) stream output 
linesize(60) title(‘$1l.kKey’)3 


vcrooeocvcveoceeoeoceevee~eetcervgteaewe pe w 


J 
is 


r 


Listing 8-10. The KEYFILE Program 
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p—do while(‘1’)$ 
read file(input) into(employee) Keyto(k)3 
Put skip list(kK+name) i 
Put file(Keys) list(namesk)§ 
if name = ‘EOF’ then 
STOPS 
end 


end Keyfileé 
Listing 8-10. (continued) 


A>dKeyfile planti 


0 Jackson 
1 Harris 

2 Robinson 
3 Wilson 

4 Smith 

5 Jones 

6 EOF 


Listing 8-11. Interaction with the KEYFILE Program 


A>dtyre Plantl.Key 
‘Jackson’ O ‘Harris’ 1 ‘Robinson’ 2 
‘Wilson’ 3 ‘Smith’ 4 ‘Jones’ S‘EOF 

6 


Listing 8-12. Contents of the Key File 


8.3.3 The UPDATE Program 


The UPDATE program in Listing 8-13 allows you to access the data base created 
by ENTER and indexed through the file created by KEYFILE. The UPDATE program 
first reads the key file, a STREAM file, into a data structure called keylist. Keylist cross- 
references the employee name with the corresponding key value in the data base. Lines 
20 to 23 declare the data structure that holds these cross-reference values, and lines 
37 to 40 fill in the data. 


Note: line 39 is not a multiple assignment statement, but rather a definition of a Boolean 
expression for the variable, eolist. 
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UPDATE opens the emp file on line 31. The OPEN statement assigns the file the 
DIRECT attribute, that allows both READ and WRITE operations with the individual 
records identified by a key value. You then enter an employee name as matchname, 
and the DO-group between lines 47 and 61 directly accesses the individual records in 
the data base. 


The direct access takes place as follows. Line 48 searches the list of names read from 
the key file. If there is a match, the READ with KEY statement on line 50 brings the 
employee record into memory from the emp file. The program displays and updates 
various fields from the console, and then rewrites the record to the data base with the 
WRITE with KEYFROM statement on line 58. UPDATE ends execution when you 
enter an EOF. 


Listing 8-14 shows three successive update sessions during which various addresses 
and work times are updated. In each session, you enter the employee name, access and 
display the record, and optionally, update the fields. The GET LIST statement is useful 
here. To change a value, you simply type the new value in the field position. If you do 
not want to change a value, entering a comma delimiter leaves the field unchanged. 


[RHEE HHH EHH EHH EEE ERE EH EH EH EEE EERE ER ER ERE HEH / 


/* This program allows you to retrieve and update */ 
/* individual records in an employee data base using */ 
/* a kKeved file. */ 
RITTER ee / 
update: 
Procedure options(main)$ 
declare 
1 employee static» 
2 name character(30) varying» 
2 address» 


3 street character(30) varying» 
3 city character(10) varying» 
3 state character(12) varying» 


3 zip fixed decimal(5)» 

2 age fixed decimal(3)» 

2 wage fixed decimal(5+2)»5 

2 hours fixed decimal(S+1)3 

declare 

21 1 Keylist(100)» 
22 2 Keyname character(30) varying» 
23 2 Keyval fixed binary 


Nee ee Bee ee ee 
OW ON OUBWNK TOC wWOOWNIOUBEUYUN 
coocoeeoeo ree eo eo ooo oo oO oe ee ee 


nN 
a 


Listing 8-13. The UPDATE Program 
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25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 do while(‘1’b)5 


b declare 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
c 
c 
co 
c 
b 
c 

43 ¢ Put skip list(‘Employee: ‘)3 
c 
c 
c 
d 
d 
e 
e 
e 
e 
e 
e 
e 
e 
e 
e 
e 
e 
d 
¢ 
b 
b 


(i+ endlist) fixed» 

eolist bit(1) static initial(‘0O’b)», 
matchname character(30) varying» 
(emp» Keys) file3 


open file(emp) update direct environment(f(128)) 
title (‘$1,EMP’); 


open file(kKeys) stream environment(b(4000)) 
title(‘$1,kKey’)3 


do i = 1 to 100 while (“eolist)$ 
get file(keys) list(Keyname(i) skeyval(i))3 
eolist = keyname(i) = ‘EOF’$ 

end3 


44 get list(matchname)$ 

45 if matchname = ‘EOF’ then 

46 StOPS 

47 do i = 1 to 1003 

48 if matchname = Keyname(i) then 

49 dos 

50 read file(emp) into(employee) 

51 Key(Keyval(i))3 

52 Put skip list( ‘Address: ‘+ 

53 streets citys state» zip)i 

54 Put skip list(* | 

55 Set list(streets citys state» zip)i 
56 Put list( ‘Hours: ’»shours» 

37 get list(hours)3 

58 write file(emp) from (employee) 

Pt) Keyfrom(Keyval(i))3 

60 
61 
62 
63 
64 


ends 
ends 
end3 


end update 


Listing 8-13. (continued) 
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A>update Plant! 

Employee: Jackson 

Address: (no street) (no city) (no state) 
‘100 W, 3rd St.’s ‘Fresno's ‘Ca.’s 93706 

Hours: 0.0 : 40.0 

Employee: Harris 

Address: (no street) (no city) (no state) 
‘2999 Serra Rd.’» ‘Chico’s ‘Ca.’s 95926 

Hours: 0.0 : 46.0 

Employee: EOF 

A>update Plantl 

Employee: Harris 

Address: 2999 Serra Rd. Chico Ca, 95926 

Hours: 46.0 : 48,0 

Employee: Wilson 

Address: (no street) (no city) (no state) 


Hours: 0.0 9 35.5 


Employee: EOF 
A>durdate Plantl 
Employee: Wilson 
Address: (no street) (no city) (no state) 
‘S56 Palm Ave.’s ‘Burbank’, ‘Ca.’» 91507 
Hours: Soen 8 


Employee: EOF 
A> 


Listing 8-14. Interaction with the UPDATE Program 
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8.3.4 The REPORT Program 


Listing 8-15 shows the REPORT program. The REPORT program uses the updated 
employee file to produce a list of employees along with their paycheck values. The 
REPORT program also accesses the employee file, but it reads the file sequentially to 
produce the desired output. The main DO-group between lines 35 and 51 reads each 
successive employee record and constructs a title line of the form, 


[name] 


followed by a dollar amount. REPORT uses the STREAM form of the WRITE 
statement, lines 41 and 50, to produce the output line. Line 40 includes the embedded 
control characters “M and “J at the end of buff to cause a carriage return and line-feed 
when writing the buffer. The REPORT program then computes the pay value and 
assigns it to the CHARACTER-VARYING string called buff, on line 44. In this 
assignment, PL/I performs an automatic data conversion from FIXED DECIMAL to 
CHARACTER, with leading blanks. REPORT also scans the leading blanks, replacing 
them by a dollar sign dash sequence to align the output, and writes the data to the report 
file. 


Listings 8-16 and 8-17 show the output from the REPORT program. In the first 
case, the command, 


A>rerport Plantl $¢con 
sends the report to the console for review. In the second case, the command, 
A>rerport Plant! Planti.ern 


sends the output to the disk file plant1.prn. You can then examine the contents of the 
file with the command: 


A>type Plantl.pPrn 
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[REE E EEE HE EKER HEHEHE REE EERE EERE EERE EEE / 
/* This program reads an employee data base and #/ 
/* prints a list of Paychecks. #/ 
[EE EK HEE H EEE EEE KEE EH EEE HEE HERE EE HEHEHE RHEE HE EEE HEHE / 
report: 
Procedure options(main)$ 
declare 
1 employee static» 
2 name character(30) varying» 
2 address» 
3 street character(30) varying» 
3 city character(10) varying» 
3 state character(12) varying» 
a: 21P fixed decimal(5)» 
2 age fixed decimal(3)+ 
2 wage fixed decimal(512)»5 
2 hours fixed decimal(5+1)3 


1 
2 
3 
4 
ss) 
6 
7 
8 


a 
a 
a 
a 
a 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 


declare 
i fixed» 
dashes character(15) static initial 


buff character(20) varying» 
(grosspay» withhold) fixed decimal(7+2)» 
(repfiles empfile) files 


open file(empfile) keyed environment(f (128) »b(4000)) 
title (‘$1.EMP’)$ 

open file(repfile) stream print environment(b(2000)) 
title('$2.$2')3 


Put list(‘Set Tor of Formss Press Return’) 
get skips 
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do while(‘1’b)3 
tread file(empfile) into(emplovee)$ 
if name = ‘EOF’ then 
stor} 
Put file(repfile) skip(2)$ 
buff = ‘C* !! name !! “)*mei'G 
write file(repfile) from (buff)§ 
SrossPay = wage * hourss 
Withhold = grosspay * 153 
buff = grosspay - withhold; 
do 1 = 1 to 15 
while (substr(buffviel) = * ')3 
ends 
i=i- i 
substr(buffelsi) = substr(dashesslrid 
write file (repfile) from(buff)$ 
end3 


end report; 


Listing 8-15. (continued) 


A>report Plantl $con 
Set Tor of Forms» Press Return 


(Jackson) 
$----229,50 


CHarris) 
$----351,.90 


CRobinson] 
CWilson] 
$----226,32 


CSmith] 


Listing 8-16. REPORT Generation to the Console 
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A>rerort Plant! Planti.prn 

Set Tor of Forms» Press Return 
A>type plantl.prn 


[Jackson] 
$----229.50 


CHarris] 
$----351,.90 


CRobinson] 
CWilson] 
$----226,32 


CSmith] 


Listing 8-17. 


References: Sections 10.1, 10.8, 


An Information Management System 


REPORT Generation to a Disk File 


End of Section 8 


11.2, 12 LRM 
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Section 9 
Label Constants, Variables, and 
Parameters 


Each of the programs presented so far ends execution either by encountering an end- 
of-file condition with a corresponding ENDFILE traceback, or by using a special data 
value that signals the end-of-data condition. The EPOLY program detects the end-of- 
data condition by checking for the special case where all three input values, x, y, and 
Z, are zero. 


Fortunately, PL/I provides more elegant ways to sense the end-of-data condition. In 
fact, sensing the end-of-data condition is just one of many facilities under the general 
heading of condition processing. Most often, handling these conditions involves labeled 
statements. You need some background in label processing before you take up the 
general topic of condition processing in Section 10. 


9.1 Labeled Statements 


It is an axiom of programming to avoid labeled statements and GOTOs because of 
the unstructured programs that result. Programs containing many labeled statements 
are often difficult for other programmers to comprehend. Such programs become 
unreadable, even to the author, as the program grows in size. 


PL/I encourages good structure by providing a comprehensive set of control structures 
in the form of iterative DO-groups with REPEAT and WHILE options. These control 
structures preclude the necessity for labeled statements in the general programming 
schema. You should use these control structures whenever possible, and limit the use 
of labeled statements to condition processing and locally-defined, computed GOTOs. 


Judicious use of labeled statements is appropriate in condition processing. The occur- 
rence of an error, such as a mistyped input data line, is easily handled by transferring 
program control to a label in an outer block, where recovery takes place. This method 
of understanding the program flow is simpler than the usual system of flags, tests, and 


return statements. 
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9.2 Program Labels 


Program labels, like other PL/I data types, fall into two broad categories: label 
constants and label variables. A label constant appears literally within the source 
program, and its value does not change during program execution. A label variable 
has no initial value, and you must assign it the value of a label constant through a 
direct assignment statement, or through the parameter assignments implicit in a sub- 
routine call. 


The following code sequence is an example of a label constant preceding a PL/I 
statement. 


on error(1) 
begins 
Put sKip list(‘Bad Input» Try Again’)$ 
goto retrys 
ends 


¥i get list(name) 3 


The statement on error(1) sets a trap for a particular condition. If the condition 
arises due to an invalid input, then control transfers to the BEGIN block, which 
Outputs an error message, and then transfers control back to the labeled statement. 
If there is no error on input, control transfers to the next statement following the 
GET LIST statement. 
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9.3 Computed GOTO 


In PL/I, a label constant can contain a single positive or negative literal subscript. 
A subscripted label constant corresponds to the target of an n-way branch, that is, a 
computed GOTO. The following code sequence shows a specific example. 


get list (x)3 
So to a(x)3 
s(-1): 
y = fil(x)s 
goto enda3 
a ¢O7s 
y = f2¢x)5 
goto endas 
a(2)55 
C324 
y = F3(xK)5 
enda: 
Put skip list(‘f(x)=‘’sy¥)35 


This code implicitly defines four label constants: q(-1), q(0), q(2), and q(3). The Com- 
piler automatically defines an internal label constant vector, 


9(-1:3) label constant 


to hold the values of these label constants. 


The preceding statement is not a valid PL/I statement, but indicates what the Compiler 
does internally when it encounters such statements in the source code. Also, when 
using such constructs, do not transfer control to a subscript that does not have a 
corresponding label-constant value. In the preceding case, a branch to q(1) produces 
undefined results. 
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9.4 Label References 


A reference to a label constant can be either local or nonlocal. A local reference to 
a label constant means that the label occurs as the target of a GOTO statement only 
in the PROCEDURE or BEGIN block that contains the GOTO. A nonlocal reference 
to a label constant means that the label occurs on the right side of an assignment to 
a label variable, as an actual parameter to a subroutine, or as the target of a GOTO 
statement in an inner nested PROCEDURE or BEGIN block. 


Although there is no functional difference between processing a locally-referenced 
and nonlocally-referenced label constant, a nonlocal reference requires additional space 
and time. For this reason, PL/I assumes that a subscripted label constant will be only 
locally referenced. If program control transfers to a subscripted label constant from 
outside the current environment, undefined results can occur. 


As an example, consider the following code sequence: 


main: 
[ Procedure options(main) 3 
Pi: 
Procedures 
goto lablis 
goto lab23 
P2: 
Procedure3 
Soto lab23 
end P23 
labi:$ 
lab2:3 


lL end P13 
end main$ 


The label constant lab1 is only locally referenced in the procedure P1, while lab2 is 
the target of both a local reference in P1 and a nonlocal reference in P2. 
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9.5 Example Program 


Listing 9-1 shows a nonfunctional program that illustrates the use of various label 
constants and variables. The label constants in the LABELS program are c(1), c(2), 
c(3), lab1, and lab2. They are defined by their literal occurrence in the program. The 
label variables are x, y, z, and g, and are defined by the declarations on lines 10 and 
38. 


At the start of execution, the label variables have undefined values. The program 
first assigns the constant value lab1 to the variable x. Label variable y then indirectly 
receives the constant value lab1 through the assignment on line 12. As a result, all 
three GOTO statements on lines 14, 15, and 16 are functionally equivalent. Each 
statement transfers control to the null statement following the label lab1 on line 32. 


The subroutine call on line 18 shows a different form of variable assignment. Lab2 
is an actual parameter sent to the procedure P, and assigned to the formal label variable 
g. In this program, the subroutine call transfers program control directly to the state- 
ment labeled lab1. 


The DO-group beginning on line 20 initializes the variable label vector z to the 
corresponding constant label vector values of c. Due to this initialization, the two 
computed GOTO statements, starting on line 25, have exactly the same effect. 


[EERE HEHEHE EEE HK EE HEE HEHE EEE HEE EHR ERE RE EH ER EER HEE EES / 
/* This is a nonfunctional program. Its purpose is #/ 
/* to illustrate the concept of label constants and */ 
/* variables, */ 
LEHRER EERE REE ERE EE HEHEHE REE E EEE LHR E RE HH KEKE RHEE EK EHE/ 


oeeene 
Procedure options(main)$ 
declare 


onNounsewnre 


i fixed, 

(x»+ y+ 2(3)) labels 
labli 
x5 


labi; 
x5 
y3 


P(lab2)35 


wTooocoorvococjvoovoo7crvri7crcri7criarcrvricovovrewewenwee wa 


Listing 9-1. An Illustration of Label Variables and Constants 
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do i=i to 35 
[ z(i)d) = clids 


ends 


20 
21 
Z2 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
a1 
42 


1 = 235 
goto 2(1)5 
goto cli) 


Procedure (9)3 
declare 
g label 
goto 93 
end Pj 


oovooodaqeoqon0oeqgmrngreoroocreoceoegceoegmgegoegrgegegaona 


end Labels3 
Listing 9-1. (continued) 


End of Section 9 


References: Sections 3.3, 8.5 LRM 
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Section 10 
Condition Processing 


Condition processing is an important facility of any production programming lan- 
guage. The language should allow a program to intercept and handle run-time error 
conditions with program-defined actions, and then continue execution. 


For example, a common condition occurs when a program is reading input data 
from an interactive console, and you inadvertently enter a value that does not conform 
to the data type of the input variable. The PL/I run-time system signals a conversion 
error, and in the absence of any program-defined action, ends program execution with 
a traceback. If this premature termination occurs after hours of data entry, it causes 
a considerable amount of wasted effort. This is unacceptable in a production environment. 


10.1 Condition Categories 
PL/I provides nine categories of conditions. They are: 


ERROR 
FIXEDOVERFLOW 
OVERFLOW 
UNDERFLOW 
ZERODIVIDE 
ENDFILE 
UNDEFINEDFILE 
KEY 

ENDPAGE 


The first five categories include all arithmetic error conditions and miscellaneous 
conditions that can arise during I/O setup and processing. They also include conversion 
errors between the various data types. The last four categories apply to a specific file 
that the run-time I/O system is accessing. Each condition has an associated subcode 
that provides information about the source of the condition. 


OQ] UONDa¢S 


10.2 Condition Processing Statements PL/I Programming Guide 


10.2 Condition Processing Statements 


The ON, REVERT, and SIGNAL statements implement condition processing in 
PL/I. The ON statement defines the actions that take place upon encountering a con- 
dition. The REVERT statement disables the ON statement, and recovers any previously 
stacked condition. The SIGNAL statement allows your program to signal various 
conditions. 


10.2.1. ON and REVERT 


The following code sequence illustrates the ON and REVERT statements inside a 
DO-group. , 


do while(‘i’b)3 

on endfile(sysin) 

EOF = ‘1i’b3 

revert endfile(sysin)s$ 
ends 


Here, both the ON and the REVERT statement execute on each iteration. Processing 
the ON and REVERT statements involves run-time overhead. To avoid this, code the 
same DO-group as follows: 


on endfile(sysin) 
EOF = ‘1’b3 
do while(‘1’b)5 


’ 


ends 


PL/I automatically executes the REVERT statement for any ON conditions that you 
enable inside a procedure block when control passes outside the bleck. The program 
shown in Listing 10-1 illustrates this concept. 
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1 GTI / 
2 /* This program is nonfunctional, Its Purpose is to */ 
3 /* illustrate how PL/I executes the ON and REVERT */ 
4 /* statements. 7 
5 | ERE H RHEE EEE EET EEE EEE / 
6 auto revert: 

7 Procedure options(main)3 
8 declare 
] i fixed» 

10 sysin files 


_ 
_ 


do i = 1 to 100003 
call Plivexit) 


exit: 
ends 
rc Ps 
Procedure (index+lab)3 

declare 
20 (t» index) fixed» 
21 lab label 
22 
fa | on endfile(sysin) 
24 goto lab 
25 
26 Put skip list(indexs‘:/)3 
=? get list(t)3 
28 if t = index then 
29 | sete lab3 
30 end Ps /* implicit REVERT supplied here */ 
31 


ee 
wowoomonoueuoan 
= ae SO = mo ~~~ — a a 


Ww 
nN 


end auto reverti 
Listing 10-1. The REVERT Program 


In the REVERT program, line 13 calls the procedure P and passes to it the actual 
parameters i, the DO-group index, and the label constant exit. The ON statement 
inside P executes every time the procedure is called. If PL/I did not supply the REVERT 
statement automatically, the Condition Stack would overflow when the value of the 
index count reached 17. Thus, REVERT has three possible ways to exit the procedure 
P 


If you enter an end-of-file character, CTRL-Z, REVERT executes the enabled ON 
condition and sends control through the label variable lab to the statement labeled 
exit. PL/I deactivates the procedure and executes the REVERT statement because the 
GOTO statement transfers control outside the environment of P. 
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The second possible exit follows the test on line 28. If you enter a value equal to 
the index, then the GOTO statement on line 29 executes and again sends control 
outside the environment of P. 


Finally, if control reaches the end of P, PL/I executes the REVERT statement and 
disables the ON condition set on line 23. No matter how control leaves the environment 
of the procedure, PL/I always disables the ON condition. 


10.2.2 SIGNAL 


The SIGNAL statement activates the ON-body, the body of statements corresponding 
to a particular ON statement. Thus, processing a SIGNAL statement has the same 
effect as when the run-time system signals the condition. 


The following code sequence illustrates the SIGNAL statement. 


on endfile(sysin) 
stops 


do while(‘1i’b)$ 
get list(buff)s 
if buff = ‘END’ then 
signal endfile(sysin)s3 
Put skip list(buff)s 
ends 


This code executes the SIGNAL statement whenever the GET LIST statement reads 
the value END from the file SYSIN. Thus, the ON condition receives control on a real 
end-of-file, or when the value END is read. 


10.3 Examples of Condition Processing 


The following two programs, FLTPOLY2 and COPYLPT, incorporate some con- 
dition processing, so you can see how these concepts are implemented. 
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10.3.1 The FLTPOLY2 Program 


Listing 10-2 shows the FLTPOLY2 program. This is essentially the same program 
listed in Section 7-1. The only difference is that it incorporates condition processing 
to intercept the end-of-file condition for the file SYSIN. If you run this program, you 
will see how you can end execution with a CTRL-Z character. Unlike FLTPOLY, if 
you enter all zeros, FLTPOLY2 simply evaluates the polynomial and prompts you for 
more input. 


oan OuwsawWwone 


a 
a 
a 
a 
a 
a 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 

18 b 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
b 
b 
c 
c 
c 
c 
c 
b 
b 


[ERG TETHER ea / 
/* This program evaluates a polynomial expression */ 
/* using FLOAT BINARY data. It also traps the end-of- #/ 
/* file condition for the file SYSIN. */ 
[RR IIIT IHE IEE / 
fltpoly2: 

Procedure orptions(main)$ 

Lreplace 


false by ‘O’b» 
true by ‘1’b$ 
declare 
(xeyez) float binary(24)+ 
eofile bit(1) static initial(false)» 
sysin files 


on endfile(sysin) 
eofile = trues 


- do while(true)3 
Put skip(2) list(‘Type xeyez: ‘)5 


get list(xryve2z)3 


if eofile then 


StOP3 
Put skip list(* 2')5 
put skip list(* K + 2y + 2 = oP(Xeyez))5 
L endi 
P; 
Procedure (x+y+z) returns (float binary(24))3 
declare 


(xeyez) float binary(24)35 
return (ke ate 2S oe ZA 
end P§ 


end fltroly23 


Listing 10-2. The FLTPOLY2 Program 
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10.3.2 The COPYLPT Program 


Listing 10-3 shows an example of I/O processing using ON conditions. The COPYLPT 
program copies a STREAM file from the disk to a PRINT file, while properly formatting 
the output line with a page header and line numbers. The program accepts console 
input to obtain the parameters for the copy operation, and provides error exits and 
retry operations for each input value. COPYLPT sets up various ON-units to intercept 
errors during the copy operation that takes place in the iterative DO-group between 
lines 71 and 76. The following sections discuss the individual parts of the program. 


[EERE REE EKER REET ETE EEE EEE HEHEHE / 

/* This Program copies a STREAM file on disk to a #*/ 

/* PRINT files and formats the output with a page */ 

/* header» and line numbers. +/ 

| RH HR REE REE RITE EE / 
r- copy: Procedure options(main)$ 


OrNOUWNBWNS 


declare 
(sysin» sourcefiles printfile) file» 
(pagesizes Pagyewidth»s spaces» linenumber) fixed» 
(line character(14),» buff character(254)) varying; 


Put list(‘*z File to Print Cory Program’) 


on endfile(sysin) 
Jo to typeovers 


tyPeover: 
Put skie(S) list(How Many Lines Per Page? ys 
get list(pagesize)3 


Put skip list(‘How Many Column Positions? ‘)3 
get skip list(pagewidth)$ 


error(1) 

begin’ 
Put list(‘Invalid Numbers Type Integer’)3 
go to getnumber3 

ends 

getnumber: 

Put skip list(‘Line Spacing (1=Single)? a 

get skip list(spaces)3 

revert error(1)3 


Put skip list(‘Destination Device/File: ‘)3 
get skip list(line)s 


a 
a 
a 
a 
a 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
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b 
b 
b 
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c 
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b 
b 
b 
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open file(printfile) print Pagesize(pagesize) 
linesize(rPagewidth) title(line)3; 


on undefinedfile(sourcefile) 
begins 
Put skip list(‘"’slines‘" isn’’t a Valid Name’)§ 
go to retry3 
end3 
retry: 
Put skip list(‘Source File to Print? se 
get list(line)$ 
open file(sourcefile) stream environment(b(8000)) 
title(line)é 
endfile(sourcefile) 
begins 
Put file(printfile) pages 
stops 
end$ 


endfile(printfile) 


stops 
ends 


endpage(printfile) 
begini 
Put file(printfile) page skir(2) 
list(‘PAGE’ spageno(rrintfile))3 
Put file(printfile) skip(4)35 
end3 


on 
on 
begins 
| Put skip list(‘*g*g°9*9 Disk is Full’)3 
on 


signal endpage(printfile)3 
do linenumber = 1 repeat(linenumber + 1)3 
get file (sourcefile) edit(buff) (a)i 
put file (printfile) 
edit(linenumbers'!‘srbuff) (f (5) 9x(1)sal(2) sa)i 
Put file (printfile) skip(spaces)i 
ends 


end copy3 
Listing 10-3. (continued) 
The COPYLPT program begins by reading five values: 


m the number of lines on each page 
@ the width of the printer line 
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® the line spacing, normally single- or double-spaced output 
@ the destination file or device 
® the source file or device 


While entering these parameters, you can type an end-of-file CTRL-Z character and 
restart the prompting. 


The PUT LIST statement on line 13 writes the initial sign-on message. Recall that 
PL/L allows control characters in string constants. Here, the first character of the message 
is a CTRL-Z, which clears the screen if you are using an ADM-3A™ CRT device. If 
you are using some other device, you can substitute the proper character and recompile 
the program. 


The ON statement of line 15 traps the ENDFILE condition for the file SYSIN, so 
that execution begins at typeover whenever the console reads an end-of-file character. 


Lines 19 through 23 read the first two parameters with no error checking other than 
detecting the end-of-file. Line 25 however, intercepts conversion errors for all operations 
that follow. If the GET statement on line 32 reads a nonnumeric field, control passes 
to the on-body between lines 26 and 29 that writes an error message, branches to 


getnumber, and retries the input operation. Following successful input of the parameter 
spaces, the REVERT statement on line 33 disables the conversion error handling. 


COPYLPT opens the input and output files between lines 38 and 50. The program 
assumes that the output file can always be opened, but detects an UNDEFINED input 
file, so you can correct the filename. 


The program executes two ON ENDFILE statements between lines 51 and 61. The 
first statement traps the input end-of-file condition and performs a page eject on the 
output file. This ensures that the printer output is at the top of a new page after 
completing the print operation. The STOP statement included in this ON-unit completes 
the processing with an exit. 


The second ON-unit intercepts the end-of-file condition on the print file. This can 
only occur if the disk file fills, so the unit prints the message, 


Disk is Full 
and ends execution. The CTRL-G character sends a series of beeps to the CRT as an 


alarm. The run-time system closes all files upon termination, so that the print file is 
intact to the full capacity of the disk. 
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Line 63 begins an ON ENDPAGE unit that intercepts the end-of-page condition for 
the print file. Whenever the run-time system signals this condition, the ON-unit moves 
to the top of the next page, skips two lines, prints the page number, and skips four 
more lines before returning to the signal source. The SIGNAL statement on line 70 
starts the print file output on a new page by sending control to the ON-unit defined 
on line 63. All subsequent ENDPAGE signals are generated by the run-time system at 
the end of each page. 


The DO-group beginning on line 71 initializes and increments a line counter on each 
iteration. The GET EDIT statement on line 72 specifies an A, alphanumeric, format. 
This fills the buffer with the next input line up to, but not including, the carriage return 
line-feed sequence. The PUT EDIT statement on line 73 writes the line to the destination 
file with a preceding line number, a blank, a vertical bar, and another blank, resulting 
from the A(2) field. If the run-time system signals the ENDPAGE condition while 
executing the PUT statement on line 75, the format item SKIP(spaces) might not be 
processed. 


Listing 10-4 shows the user interaction with the COPYLPT program. Here, the source 
file is the LABELS.PLI program, and $LST, the physical printer, is the destination. 


A>corpylpt 
File to Print Cory Program 


How Many Lines Per Page? 

How Many Column Positions? 

Line Spacing (1=Single)? 

Invalid Number» Type Integer 

Line Spacing (1=Single)? 1 
Destination Device/File: $1st 
Source File to Print? copy.Pil 


copy.Pil " isn’t a Valid Name 
Source File to Print? coPy+Pli 
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Listing 10-5 shows two pages of output produced by the program. 


PAGE 


[EHR KEKE EEE EEE EEE EE ETT EE / 
/* This program copies one file to another using #/ 
/* buffered I/0. */ 
[HHH KEKE ERE RE EE EERE ETT EE / 
copy: 

Procedure options(main) 3 

declare 

(input_file,soutput file) files 


OrNOuUBSWONe 


open file (input file) stream 
environment(b(8192)) title(‘$1.$1')5 


open file (outrut_ file) stream output 
environment(b(8192)) title(‘$2,$2')5 
declare 
buff character(254) varyingi 


do while(‘1’b)3 
read file (input file) into (buff)i 
write file (output file) from (buff)i 


ends 
end copy$ 
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This example shows that you can incorporate error handling in your programs to 
make them easier to use. In fact, you could enhance the COPYLPT program to handle 
errors in the first two input lines, or errors in the destination filename. 


To gain further experience, you could go back over all the previous examples and 
add ON-units to trap invalid input data and end-of-file conditions. Modifying these 
small programs gives you a good foundation in condition processing. 


End of Section 10 


References: Section 9 LRM 


End of Section 10 PL/I Programming Guide 


ALL INFORMATION PRESENTED HERE iS PROPRIETARY TO DIGITA 


Section 1 1 
Character String Processing 


PL/I provides powerful character-string handling capabilities essential in a commer- 
cial production language. This section presents two sample programs that illustrate 
the use of some PL/I character-string functions. After you read the text and study the 
sample programs, you can make changes in the programs to expand your knowledge 
of PL/I. 


11.1 The OPTIMIST Program 


Our first example of string processing is a program called the OPTIMIST. The 
OPTIMIST program turns a negative sentence into a positive sentence. The OPTIMIST 
performs this task by using the character-string facilities of PL/I. 


Listing 11-1 shows the OPTIMIST program. The first segment, between lines 12 and 
23, defines the data items used in the program. The remaining portion reads a sentence 
from the console, ending with a period, and retypes the sentence in its positive form. 
Listing 11-2 shows a sample console interaction with the OPTIMIST. The OPTIMIST 
works well if sentences are simple, but complicated sentences confuse the program. 


Line 13 gives the OPTIMIST vocabulary of negative words, with the corresponding 
positive words on line 15. Thus, never becomes always, and none becomes all. OPTI- 
MIST replaces the word not with an empty string. Lines 17 through 20 declare the 
upper- and lower-case alphabets for case translation in the sentence processing section. 


OPTIMIST constructs each successive input sentence between lines 28 and 32, where 
the DO-group reads another word, and concatenates the word on the end of the 
sentence. The SUBSTR test in the DO WHILE heading checks for a period at the end. 


Note: OPTIMIST can only accept a sentence whose maximum length is 254 characters. 
PL/I discards any additional characters. 


After reading the complete sentence, OPTIMIST translates all upper-case characters 
to lower-case to scan the negative words. It performs this case translation on line 33 
by using the built-in TRANSLATE function. OPTIMIST uses the built-in VERIFY 
function on line 34 to ensure that the sentence consists only of letters and a period. 
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If the sentence consists of characters other than letters or a period, the VERIFY function 
returns the first nonzero position that does not match, and the OPTIMIST responds 
with: 


Actuallys that’s an interesting idea, 


If the VERIFY function returns a zero value, then the sentence contains only trans- 
lated lower-case letters and a period. In this case, control transfers to the DO-group 
between lines 36 and 42. On each iteration, OPTIMIST uses the built-in INDEX 
function to search for the next negative word, given by negative (i). If found, it sets j to 
the position of the negative word, and in the assignment statement on line 39, replaces it 
with the corresponding positive word. In this assignment, the portion of the sentence 
that occurs before the negative word is given by, 


substr(sent+l+J-1) 
while the replacement value for the negative word is given by, 
Positive(i) 


and the portion of the sentence that follows the negative word being replaced is given 
by: 


substr(sentrsitlength(negative(i))) 


The OPTIMIST concatenates these three segments to produce a new sentence with 
the negative word replaced by the positive word. It then sends the resulting sentence 
to the console, and loops back to read another input. Because all negative words have 
a leading blank, the negative portion is always found at the beginning of a word. Thus, 
OPTIMIST replaces nevermind with alwaysmind. This can produce interesting results. 


You could make at least three improvements to the OPTIMIST. First, if the sentence 
exceeds 254 characters, the input scan never stops, because the period is not found. 
You could include a check to ensure that the newly appended word does not exceed 
the maximum size. 


Second, there is no condition processing in the DO-group between lines 25 and 45, 
so the OPTIMIST never stops talking. It ends only through input of a CTRL-Z, end- 
of-file, or CTRL-C, system warm start. You could include an ON-unit to detect an 
end-of-file to end the program in a reasonable fashion. 


Finally, you could try to make the OPTIMIST smarter! 
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Ss 
SCWOONMUWBWONK THO ODNOUWBEHYONY 


11.1 The OPTIMIST Program 


| RRR / 
/* This program demonstrates PL/I character string */ 
/* Processing by turning a negative sentence into a */ 


/* Positive one, 


*/ 


[KEKE HE ERE HEHEHE EHH EH HEHEHE EEE EEE HER ERE EEE RE RHEE / 


optimist: 


Procedure options(main)3 


“replace 
true by ‘i’bs 
false by ‘O‘’b» 
nwords by 53 
declare 
negative (1:nwords) 


(* never’s* none’s* nothing’s* not’»s 


Positive (l1l:nwords) 


character(8) varying static initial 
~ Neds 
character(10) varying static initial 


ae 


(’ always’+s* all’s* something’+* ‘+’ some’)» 


upper character(28) 


static initial 


(*ABCDEFGHIJKLMNOPORSTUYWXYZ. ‘) 5 


lower character(28) 


static initial 


(‘abcdefghidklmnoparstuuwxyz. ‘)+ 


sent character(254) 
word character(32) 


varying» 
varying» 


mn ny 
On 


(ied) fixeds 


do while(true)$ 
Put skip list(‘What’’s up? ‘)3 
sent = ‘* ‘§ 
do while 
(substr(sentrlength(sent) ) ae 
get list (word) 
sent = sent !! * ’ !! words 
end3 
sent = translate(sentslowersupPrer)$ 
if verify(sent»slower) “= 0 then 
sent = ‘ that’‘is an interesting idea, 
do i = 1 to nwords3 
ji = index(sentsnegative(i))$ 
if j *= 0 then 
sent = substr(sentrylrj-1) !! 
Positive(i) !! 
substr(sentritlength(negative(i)))35 
end3 
Put list(‘Actuallys’!!sent)i 
Put skip 
ends 


24 
25 
26 


rn 
~~ 


on nr 
ow ow 


WUWUNHWOWNWWW WY 
woonowneruwnre 


eBo 
- oO 


eBSseacoss 
aounnrwn 


a 
~ 


end optimists 
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A>dorptimist 


What’s up? 
Actually» 


What‘’s up? 
Actually» 


What‘s up? 
Actually» 


What‘’s up? 
Actually» 


What‘s up? 
Actually» 


What‘s up? 
Actually» 


What’s up? 
Actually» 


What’s up? 
Actually» 


What's up? 
Actually» 


What’s up? 
Actually: 


What‘s up? 
Actually» 


What’s up? 
Actually» 


What’s up? 
Actually» 


What’s up? 
Actually» 


Nothing is uP. 
something is uP, 


This is not fun. 
this is fun. 


Programs like this never make sense, 
Programs like this always make sense, 


Nothing is easy that 15 not complicated, 
something is easy that is complicated, 


Nobody cares and its none of your business, 
somebody cares and its all of your business, 


The price of everything. 
the price of everything, 


Boy are you stupid, 
boy are you stupid, 


Dont get smart with me, 
dont get smart with me, 


You started it I didnt, 
you started it 1 didnt, 


No I did not. 
some i did, 


Thats better, 
thats better. 


You are hard to talk to. 
you are hard to talk to. 


There you go agains 
there you go again» 


Thats it I quit, 
thats it i quit, 
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What‘s up? Stop that, 
Actually» stop that, 


What’s up? If you dont stop I will Pull your Plug, 
Actuallys if you dont stop i will pull your Plug, 


What’s up? You can not Pull my Plug, 
Actually: you can pull my Plug, 


What’s up? I Know, 
Actually» i Know, 


What’s up? “Z 


END OF FILE (1)» File: SYSIN=CON 
Traceback: O9C5 0970 0157 4100 # 0909 0529 8090 0157 
A> 


Listing 11-2. (continued) 


11.2 A Parse Function 


This section presents a more practical application of string processing. It is often 
useful to have a separate subroutine in a program that reads a line of input and separates 
it into individual numbers and characters. Such a subroutine is called a parser, or a 
free-field scanner. The FSCAN program, shown in Listing 11-3, gives an example of 
a parser. 


FSCAN demonstrates the embedded subroutine called GNT, Get Next Token, which 
parses an input line into separate items called tokens. Once you test GNT, you can 
extract it from this program and put it into a production program where required. 
Section 13.4 uses GNT to compute values of arithmetic expressions. 


Listing 11-4 shows interaction with the FSCAN program. FSCAN reads a line of 
input, parses the line into separate tokens, and then writes the tokens back to the 
console, with surrounding apostrophes. The tokens are just numeric values, such as 
1234.56, or individual letters and special characters. GNT bypasses all intervening 
blanks between the tokens in the token scan. 


The FSCAN program has three parts. The first part, lines 10 to 12, defines the global 
data area called token, used by the GNT procedure. The second part, lines 14 to 42, 
is the GNT procedure itself. The third part is the DO-group between lines 44 and 47 
that performs the test of the GNT function procedure. 
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[FTTH / 
/* This program tests the procedure called GNT» a #/ 
/* free-field scanner (parser) that reads a line #*/ 
/* of input and breaks it into individual parts. #/ 
[RRR RHR IE EE EEE EEE EEE / 
fscan: 
Procedure options(main) 3 
hreplace 
true by ‘1’b3 
declare 
token character(80) varying 
static initial(‘’)3$ 


gnt: 
Procedures 
declare 
i fixed» 
line character(80) varying 
static initial(‘’)§ 


Nee Re ee ee eee 
SOCOM N ODUM BHWO NK CHWOONIOUWM EW Ne 


Nn 
_ 


line = substr(lineslength(token)+1)5 
do while(true) 
if line = ‘’ then 
get edit(line) 
i = verify(lines* 
if i = 0 then 
line = ‘’35 
else 
do3 
line = substr(linesi)$ 
i = verify(line»‘0123456789.')3§ 


if i = 0 then 
[ token = line 


else 


23 
24 
25 


NN 
uo 


ON N 
own 


WWW WW 
OW BWNe 


w 
a 


if i = 1 then 
L token = substr(linesl+1)3 
else 
token = substr(lineslri-1)3 
returni 
end3 
end} 
end gnt3 


SE euunw N 
Nr oOwWoOn nN 
ooaonvnti nv ov 7D DT wD wMOMOMOWMWHOHK HAA KA KAA oOKnT KM NO KDW no Tee TTF Te Te ewe oe eae eee se 
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44c do while(true)3 
45 ¢ call gnt3 
46 ¢ Put edit(’***!!token!!//’') (x(t) sari 
47 ¢ end§ 
48 b 
49 b end fscani 
Listing 11-3. (continued) 

A>fscan 

88+9.9 

b 88 oF ‘ + a ay 9 ‘ 9 


1234567 89.10 
‘1234567’ ‘89,10’ 
1121314151657 


a ey em a le a a i aR 
160 BGGe eee 76747s 

Syne BBBe eee! S707 070! 

4 


End of File (7)» File: SYSIN=CON 
Traceback: OBGE 27CA 0143 OOFF # 0B78 0986 0143 O1FS 
A> 
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11.2.1 The GNT Procedure 


GNT stores the input line in the character variable called line that is initially empty 
due to the declaration on line 18. On the first call, GNT extracts the first portion of 
line and places it in token, which becomes the next input item. On each successive 
call, GNT removes the previous token value from the beginning of a line before scanning 
the next item. 


For example, suppose the input line is, 


166K88*9.9 


where & represents a blank character. On the first call to GNT, both token and line 
are empty strings. The assignment on line 21 removes the previous value of token and 
leaves line as an empty string. The DO-group between lines 22 and 41 ensures that 
the line buffer is always filled. If GNT encounters an empty buffer, the GET EDIT 
statement, line 24, immediately refills it. The call to the built-in VERIFY function on 
line 25 returns the first position in line that is not blank. 
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If VERIFY returns a 0, then the entire line is blank and must be cleared. The refill 
operation takes place on the next iteration. If the line is not entirely blank, then control 
transfers to the DO-group beginning on line 29. 


11.2.2. The DO-Group 


Processing in the DO-group takes place as follows. On entry, the value of i is the 
first nonblank position of the line buffer. Thus, the statement on line 30 removes the 
preceding blanks from line, so the next token starts at the first position. GNT then 
calls the VERIFY function to determine if the next item in line is a number. 


The assignment statement on line 31 sets i to O if the entire buffer consists of numbers 
and decimal points. Line 31 sets ito 1 if the first item is not anumber or a period. It sets i 
to a larger value than 1 if the first item is a number that does not extend through the 
entire line buffer. Thus, this sequence of tests, starting at line 32, either extracts the entire 
line (i= 0), the first character of the line (i= 1), or the first portion of the line (i >1). 


In the preceding example input line, on the first iteration GNT sets line to, 
b Bb B 8&8 8B * 9 . 9 
1 2 3 4 5 6 7 8 9 


where the index 1 through 9, in line, is shown below each character. On line 30, GNT 
removes the initial blanks, leaving line as: 


Line 31 calls the VERIFY function that locates the first position containing a nondigit 
or period character. In this case, VERIFY returns the value 3, which corresponds to 
the * in position 3. As a result of the tests, FSCAN executes line 38 and produces the 
equivalent of: 


substr(‘88*9,97% +1 +2) 


This results in a token value of 88, which is the next number in line. 
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On the next call, GNT removes token from line using the SUBSTR operation on 
line 21 and leaves line as: 


The VERIFY function on line 31 returns the value 1, because the leading position 
of line is not a digit or a period. Line 36 extracts and returns the first character of line 
as the value of token. 


The third call to GNT gets the last token in line by first extracting the *. This leaves 
line as: 


This time, because all characters are either digits or periods, the VERIFY function 
returns a 0 and GNT executes line 33. This results in a token value of 9.9, which is 
the remainder of line. 


The fourth call to GNT clears the previous value of token from line, so that line is 
the empty string. This causes GNT to execute the GET EDIT statement, line 24, and 
refill line from the console. Execution proceeds in this manner until you stop the 
program with a CTRL-Z or CTRL-C input. 


This simple parser has some obvious flaws. It does not trap end-of-file conditions. 
You could include an ON-unit to detect this condition, and return a null token value 
to indicate there’ is no more input. Furthermore, GNT does not detect multiple period 
characters. This would cause a subsequent conversion signal (ERROR(1)) if you attempt 
to convert to a decimal value. 


These enhancements give you an improved version of GNT that you can incorporate 
into any of your programs. 


End of Section 11 


References: Sections 3.2, 6.4, 6.8 LRM 
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Section 12 
List Processing 


For some programs it is difficult to determine the exact memory requirements before 
the program runs. List processing is an example of this kind of program because the 
number of data elements can vary considerably while the program is running. 


PL/I has subroutines in the Run-time Subroutine Library (RSL) that dynamically 
manage storage allocation. When the operating system loads a PL/I program into the 
Transient Program Area (TPA) or partition, PL/I first initializes all the remaining free 
memory as a linked list. The list elements contain information fields and pointers to 
other list elements. A program dynamically allocates memory by using the ALLOCATE 
statement and releases memory using the FREE statement. PL/I continuously keeps all 
memory segments connected to one another by using the linked-list mechanism. 


The programs in this section illustrate list processing in two cases where it is not 
easy to predetermine the amount of storage required. 


12.1 Based and Pointer Variables 


You can visualize a based variable as a template that fits over a region of memory 
but has no storage directly allocated to it. A pointer variable is just a two-byte value 
that holds the address of a variable. When you use a pointer variable, you are pro- 
grammatically placing this based variable template over a particular piece of memory. 
The method depends on the form of the based variable declaration. 


If the based variable declaration does not include an implied base, then you must 
qualify any reference to the based variable with a pointer. If the based variable dec- 
laration includes an implied base, then you can include a pointer qualifier in any 
reference to the based variable, or you can simply use the implied pointer given in the 
declaration as a base. 
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Consider the following example declaration: 


declare 
i fixed, 
mat(O:5) fixed, 
(P+ 9) Pointers 
x fixed based, 
y fixed based(p)s 
z fixed based(f())5 


PL/I allocates storage for the two variables i and mat because they are not based 
variables. PL/I also assigns storage locations for the two pointer variables p and q. 
However, the three variables x, y, and z are declared as based variables, and they have 
no storage locations prior to execution. Instead, PL/I determines their actual storage 
addresses as the program runs. The variable x has no implied base, so every reference 
to x must have a pointer qualifier such as: 


P->x = 53 


65 


The first statement assigns the value 5 to the fixed two-byte variable at the memory 
location given by p. The second statement assigns the value 6 to the location given by 


q. 


The variable y, on the other hand, has an implied base that means you can reference 
it with or without a pointer qualifier. The reference 


= 35 


equals 


and thus, 
y = 33 


have exactly the same effect as the two preceding assignments to x. 
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The variable z, like the variable y, has an implied base. In this case, the base is an 
invocation of a pointer-valued function with no arguments. For example, the function 
f can take the form: 


Ts 
Procedure returns(pPointer)s 
return (addr(mat(i)))3$ 

end f3 


Using this definition of f, you can reference z as: 


= 55 


z= 63 


The first form is equivalent to those shown above, with the location derived from the 
pointer variable p. The second form however, is an abbreviation for: 


f() -> z2 = 65 


In this case, PL/I evaluates the function f to produce the storage address for the based 
variable z. This form has a twofold advantage. First, the pointer-valued expression can 
be complex, and not restricted to a simple pointer variable. Second, the code for function 
f appears only once, rather than being duplicated at each variable reference. This can 
save a considerable amount of space in a program. 


Note: the implied base must be in the scope of the declaration for the based variable. 
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The following incorrect code sequence illustrates this concept: 


mains 
Procedure orptions(main) § 
declare 
x based(P) + 
y based(q)+ 
P Pointers 
begins 
declare 
(Psa) Pointers 
x 33 
Y 1035 
ends 
declare 
9 Pointers 
end main$ 


Because the variables x and y are based on p and q, the pointers p and q must be 
in the same or encompassing scope. Here the pointers p and q are declared in the 
embedded BEGIN block that is a different environment. 


12.2 The REVERSE Program 


Our first example of list processing is a program called REVERSE. The OPTIMIST 
program in Section 11 can accept a sentence with a maximum of 254 characters, the 
maximum string length. REVERSE, however, accepts sentences of virtually any length 
by using a list structure instead of a single character string. Instead of performing word 
substitution, REVERSE simply reverses the input sentence. 


Listing 12-1 shows the REVERSE program, which is divided into three parts. The 
first part, lines 12 through 17, reads a sentence from the console and writes the sentence 
back to the console in reverse order. Each input sentence consists of a sequence of 
words up to 35 characters in length. This is sufficient to hold, 

supercalifragilisticexpialidocious 


one of the longest words in the English language. 


To simplify the input processing, REVERSE requires a space before the period that 
ends the sentence. REVERSE also ends execution when you type an empty sentence. 
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The second part of REVERSE is a separate subroutine, called read_- it, which starts on 
line 19. The third part is a subroutine called write_it, which begins on line 37. Making 
these functions separate subroutines in the main program simplifies the overall structure. 


Listing 12-2 shows the console interaction with REVERSE. 


1 REE EERIE TEETH HE HEH / 
/* This program reads a sentence and reverses it, */ 
TG Ieee / 
reverse: 
Procedure options(main)$ 
declare 
sentence Pointer» 
1 wordnode based (sentence) » 
2 word character(35) varying» 
2 next Pointers 


do while(‘1’b)3 
call read it()i 
if sentence = null then 
stops 
call write it()3 
ends 


read it: 
Procedures 
declare 
newword character(35) varying» 
newnode Pointers 
sentence = null 
Put skip list(‘What’’s up? ‘)3 
do while(‘1’b)3 
get list(newword)3 
if newword = ‘,’ then 
returns 
allocate wordnode set (newnode)$ 
newnode->next sentences 
sentence newnode$ 
word newword$ 
ends 
end read iti 
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write it: 
q Procedure} 


declare 
P Pointers 
Put skip list(‘Actuallys ‘)5 
do while (sentence *= null); 
Put list(word)3 
P = sentence 
sentence = nexti 
free p->wordnodes 
ends 
put list(‘.’)3 
Put skips 
end write iti 


reverse3 
Listing 12-1. (continued) 

A>reverse 
What’s up? North is up , 
Actually» up is North . 
What‘’s up? The rain in Spain falls mainly in the Plain . 
Actually: plain the in mainly falls Spain in rain The . 
What‘’s up? 
Actually» 
What’s up? 


A> 


Listing 12-2. Interaction with the REVERSE Program 


The REVERSE program stores each word in a separate area of memory, obtained 
using the ALLOCATE statement on line 30. On each iteration of the DO-group, the 
ALLOCATE statement obtains a unique section of the free memory space sufficiently 
large to hold the wordnode structure defined on line 8. The wordnode elements are 
linked together through the next field of each allocation, and the beginning of the list 
is given by the value of the sentence pointer variable. 
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Each allocation consumes 38 bytes. You can verify this by examining the Symbol 
Table. The wordnode structure is 38 bytes long because word is declared as CHAR- 
ACTER(35) VARYING, and requires one byte to hold the current length, 35 bytes to 
hold the string itself, and is followed by a two-byte pointer value. 


For example, given the input sentence, 
I SHALL RETURN . 


REVERSE executes the ALLOCATE statement three times, once for each word in the 
list. 


Suppose that these three memory allocations are found at addresses 1000, 2000, 
and 3000. The REVERSE program begins by reading the sentence in the main DO- 
group in the read_it procedure. It initializes the sentence pointer to the null address 
(0000). Upon entering the DO-group at line 26, the value of sentence appears as follows: 


SENTENCE: 0000 


REVERSE reads the first word with the GET statement on line 27, and because the 
value is not a period, it allocates the first 38-byte area to hold the word. As it constructs 
the sentence, REVERSE places the pointer value of the sentence variable into the next 
field, and the input word into the word field. The most recently read word then becomes 
the new head of the list. After processing the word I, the list appears as shown below: 


SENTENCE: 1000 


0000 


REVERSE then proceeds through the loop again. This time, it reads the word SHALL 
and allocates the second 38-byte area. The newly allocated area becomes the new head 
of the list, with the resulting pointer structure: 


SENTENCE 2000 


2000:| SHALL 1000: Le] 
1000 / 0000 
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REVERSE repeats the loop once again and processes the last word, RETURN, and 
allocates the final 38-byte area, placing it at the head of the list that results in the 
following sequence of nodes: 


“SENTENCE: 3000 


3000: |RETURN| 2000:| SHALL 1000: Pd 
2000 PA 1000 / 0000 


The program follows the pointer structure from the sentence variable to the node for 
RETURN, then to the node for SHALL, and finally to the node for I, where it encounters 
an end-of-list value 0000. 


REVERSE actually builds the list in reverse order. The DO-group in the write_it 
procedure, lines 42 to 47, simply searches through the list, starting at the sentence 
pointer, and prints each word it encounters. As soon as the word is written, the FREE 
statement on line 46 releases the 38-byte area allocated to it. The write_it procedure 
moves the sentence pointer variable to the next item in the list before it executes the 
FREE statement to free the current element. 


Note: storage does not remain intact after it is released. 


The advantage of the list structure is that the sentence can be arbitrarily long, limited 
only by the size of available memory. The disadvantage, of course, is that there is 
considerably more storage consumed for sentences that could be represented by a 254- 
character string. 


12.3. A Network Analysis Program 


The next example is extensive and illustrates two points. First, it demonstrates the 
power of PL/I list-handling constructs. Second, it shows how to divide a large, complex 
program into small, logically distinct units, and thereby simplify the coding task. 


The NETWORK program shown in Listing 12-4 performs a network analysis. That 
is, it finds the shortest path between nodes in a network. The user enters a network 
of cities and distances between the cities. Then NETWORK constructs a connected set 
of nodes using list processing structures. Upon demand from the user, NETWORK 
computes the shortest path from all cities in the network to the assigned destination, 
and then selectively displays particular optimal paths through the network. 
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It is easier to understand how the program operates if you first examine the console 
interaction shown in Listing 12-3. First, you enter a list of cities and distances between 
the cities, ending the entry with a CTRL-Z. Entering a CTRL-Z triggers a display of 
the entire network to aid in detection of input errors. NETWORK then prompts you 
for a destination city, in this case, Tijuana, and a starting city, in this case, Boise. 


NETWORK then displays a best route. There can be several of equal length. Next, 
NETWORK prompts for another starting city. If you enter a CTRL-Z, NETWORK 
reverts to another destination prompt, leaving the network intact. Interaction continues 
in this manner until you enter a CTRL-Z in response to the destination prompt. When 
this occurs, NETWORK clears the network and returns to accept an entirely new 
network of cities and distances. The entire program ends if you enter an empty network 
at this point, for example, a CTRL-Z. 


A>network 

Type "CitylsDist» City2" 
Seattles 150+ Boise 

Boises 300+ Modesto 
Seattle» 4001 Modesto 
Modesto+s 150+ Monterey 
Modesto 50+ San-Francisco 
San-Francisco: 200+ Las-Vegas 
Las-Vegas+ 350+ Monterey 
Los-Angeles» 400+ Las-Vegas 
Bakersfield» 300% Monterey 
Bakersfield» 250+ Las-Vegas 
Los-Angeles» 450+ TiJjuana 
Tidjuanas 700+ Las-Vegas 
Las-Vegas+ 920+ Boise 
Pacific-Grove: 5+ Monterey 
XZ. 


Pacific-Grove : 
S miles to Monterey 

Tijuana : 

700 miles to Las-Vegas 

450 miles to Los-Angeles 
Bakersfield : 

250 miles to Las-Vegas 

300 miles to Monterey 
Los-Angeles : 

450 miles to TiJjuana 

400 miles to Las-Vegas 
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Las-Vegas : 
920 miles to Boise 
700 miles to TiJuana 
250 miles to Bakersfield 
400 miles to Los-Angeles 
350 miles to Monterey 
200 miles to San-Francisco 
San-Francisco : 
200 miles to Las-Vegas 
50 miles to Modesto 
Monterey : 
S miles to Pacific-Grove 
300 miles to Bakersfield 
350 miles to Las-Vegas 
150 miles to Modesto 
Modesto : 
50 miles to San-Francisco 
150 miles to Monterey 
400 miles to Seattle 
300 miles to Boise 


920 miles to Las-Vegas 

300 miles to Modesto 

150 miles to Seattle 
Seattle : 

400 miles to Modesto 

150 miles to Boise 


Type Destination TiJuana 


Type Start Boise 


1250 miles remain» to Modesto 
950 miles remains to San-Francisco 
900 miles remain» to Las-Vegas 
700 miles remain» to TiJuana 
Type Start “Z 
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Destination Pacific-Crove 
Start Seattle 
555 miles remain» 400 miles to Modesto 
155 miles remain» 150 miles to Monterey 
S miles remain» 5 miles to Pacific-Grove 
Start *Z 


Destination “2 


"Cityl» Dist» City2" 


Listing 12-3. (continued) 


12.3.1 NETWORK List Structures 


NETWORK uses two data structures as list elements. The first structure is called a 
city_node and corresponds to a particular city. It is defined on line 16 of Listing 12- 
4. The city_node structure is shown below: 


total_ distance 
investigate 
city_list 


The city_name field holds the character-string value of the city’s name, while the 
total_ distance and investigate fields are used by the shortest_distance procedure. The 
city_list and route_head pointer values link together all the cities in the network. 


The second structure is called a route_node, and is defined on line 23. A route_node 
establishes a single connection between a city and one of its neighbors. You allocate 
several route_nodes for a city, corresponding to the number of connections to its 
neighboring cities. The route_node structure is shown below: 


ROUTE_NODE: 


route_list 
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The list of route_nodes associated with a particular city begins at the pointer value 
called route_head that is a part of the city_node structure. The route is determined by 
following the route_list pointer to additional route_nodes, until you encounter a rou- 
te_node with a null entry in the route_list. Each route_node also has a pointer value, 
denoted by next_city, that leads to a neighboring city_node, along with a route_dist- 
ance field that gives the mileage to the next city. 


The following example illustrates this concept. Assume Monterey is 350 miles from 
Las Vegas. NETWORK must allocate two city_nodes and two route_nodes with sample 
addresses to the left of each allocation as follows. You can temporarily ignore the fields 
marked x in the diagram. 


CITY_NODE CITY_NODE 
1000 Monterey 2000 
XXXXXKX 
XXXXXXX XXXXXXX 
XXXXXKX 
3000 


4000 


ROUTE_NODE ROUTE_NODE 


3000 2000 4000 
350 350 
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A linked list, starting at city_head, leads to all cities in the network. Given the 
preceding two cities, the list of cities appears as follows: 


CITY_HEAD 


1000 


CITY_NODE CITY_NODE 


Las Vegas 
XXXXXXX 
XXXXXXX 


0000 


Several of the procedures in NETWORK use one particular form of an iterative DO- 
group to traverse the linked lists. The statement on line 95 is typical: 


1000 Monterey 


12.3.2 Traversing the Linked Lists 


do Pp = city _head repeat (p->city_list) while (pP*=null)i 


The DO-group header successively processes each element of the linked list starting at 
city_head until it encounters a null link, 0000. On the first iteration, the DO-group 
sets the pointer variable p to the value of the pointer variable city_head. In the example 
above, this results in the assignment p = 1000. 


On the next iteration, p takes on the value of the city_list field at 1000 that addresses 
Las Vegas. This results in the value p = 2000. On the last iteration, p takes on the 
value of the city_list field based at 2000, resulting in p = 0000. The DO-group then 
stops executing because p is equal to null. 
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12.3.3 Overall Program Structure 


Keeping in mind the preceding discussion, look at the overall program structure. 
The top-level program calls occur in the DO-group between lines 31 and 38. The 
remainder of the program consists entirely of the nested subroutines described below. 


NETWORK is logically divided into four parts: 


= The input section constructs and echoes the network of cities, consisting of four 
procedures beginning on line 45: setup, connect, find, and print_all. 


@ The analysis of the shortest path between the cities takes place in the 
shortest_distance procedure starting on line 164. 


@ The shortest path display operations are split between the two procedures 
print_paths and print_route, respectively. 


@ The free_all procedure clears the old network before loading a new network. 


Beginning on line 32, the main program calls setup to read the network. If the 
city_list is empty, then NETWORK stops. Otherwise, it calls print_all to display the 
network, and then calls print_paths to prompt and display the shortest routes. Upon 
return, NETWORK calls free_all to release storage. This process continues until you 
enter an empty network. 


12.3.4 The Setup Procedure 


The main loop in setup occurs between lines 54 and 58. On each iteration, the GET 
LIST statement, line 55, reads a pair of cities with a connecting distance. Next, setup 
calls the connect subroutine twice to establish the connection in both directions between 
the cities. The ON-unit on line 50 intercepts the CTRL-Z. 


12.3.5 The Connect Procedure 


The connect procedure establishes a single route_node to connect the first city to 
the second city. The connect procedure does this by calling the find procedure twice, 
once for the first city and once for the second city. The find procedure locates a city 
if it exists in the network, or creates the city_node if it does not yet exist. Upon return 
from find, the connect procedure creates and fills in the route_node, lines 79 to 82. 
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In the previous example, the first call to connect establishes the city_nodes for 
Monterey and Las Vegas, indirectly through the find procedure, and then produces the 
route_node under Monterey only. The second call to connect establishes the route_node 
under Las Vegas. 


12.3.6 The Find Procedure 


The find procedure, starting at line 89, searches the city_list, beginning at city_head, 
until it finds the input city or exhausts the city_list. If the input city does not exist, 
find creates it between lines 100 and 105. In any case, find returns a pointer to the 
requested city_node. 


12.3.7 The Print_All Procedure 


The print_all procedure appears between lines 113 and 127. NETWORK calls 
print_all after creating the network. This procedure starts at city_head and displays 
all the cities in the city_list. As it visits each city, print_all also traverses and dis- 
plays the route_head. Upon completion of the print_all procedure, all city_nodes and 
route_nodes have been visited and displayed. 


12.3.8 The Print_Paths Procedure 


The print_paths procedure reads a destination city on line 143 and sends it to the 
shortest_distance procedure. Upon return, print_paths sets the total_ distance field of 
each city_node to the total distance from the destination city. You enter the starting 
city on line 148, and print_paths sends it to the print_route procedure for the display 
operation. 


12.3.9 The Print_Route Procedure 


The print_route procedure at line 214 displays the best route from the input city to 
the destination. The procedure finds the best route as follows: The total distance from 
the input city to the destination has already been computed and stored in the 
total_distance field. The procedure obtains the first leg of the best route by finding a 
neighboring city whose total_distance field differs by exactly the distance to the neigh- 
bor. It then displays the neighbor, moves to the neighboring city, and repeats the same 
operation. Eventually, it reaches the destination city and completes the display operation. 


Line 221 finds the original city_node. Line 231 displays the remaining distance, and 
the search for the first or next leg occurs between lines 233 and 244. On each iteration, 
line 236 tests to determine if a neighbor has been found whose total distance plus the 
leg distance matches the current city. If so, line 238 displays the leg distance and the 
search terminates by setting q to null. 
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12.3.10 The Shortest_Distance Procedure 


This procedure takes an input city, called the destination, and computes the minimum 
total distance from every city in the network to the destination. It then records this 
total at each city_node in the total_distance field. In calculating the minimum total 
distance, the procedure implements the following algorithm: 


1. Initially mark all total_distance fields with infinity, 32767 in PL/I, to indicate 
that the node currently has no connection. 


2. Set the investigate flag to false for each city. The investigate flag marks a 
city_node that needs further processing. 


3. Set the total_distance to the destination at zero; all others are currently set 
to infinity, but change during processing. 


4. Set the investigate flag to true for the destination only. 


5. Examine the city_list for the city_node that has the least total_distance, and 
whose investigate flag is true. At first, only the destination is found. When no 
city_node has a true investigate flag, all processing is complete and all min- 
imum total_distance fields have been computed. 


6. Clear the investigate flag for the city found in 4, and extract the current value 
of its total_distance field. Examine each of its neighbors; if the current 
total_distance field plus the leg distance is less than the total_distance field 
marked at the neighbor, then replace the neighbor’s total_distance field by 
this sum. Then mark the neighbor for processing by setting its investigate flag 
to true. After processing each neighbor, return to step 4. 


The algorithm thus proceeds through the network, developing the shortest path to 
any node, and as a result, visiting each city exactly once. This is because the process 
is linear, and any additional nodes do not significantly effect the time to analyze the 
network. 


12.3.11 The Free_All Procedure 


The final procedure, free_all starting at line 251, returns the network storage at the 
end of processing each network. The procedure visits and then discards each city_node 
and the entire list of route_node connections. 
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12.3.12 NETWORK Expansion 


You can expand NETWORK in several ways. First, you can open a STREAM file 
and read the graph from disk, because it is inconvenient to type an entire network 
each time you run the program. You can also store several networks on disk and 
retrieve them on command from the console. 


[| EERE HEHEHE EE EEE EEE ER EEE EERE HEE EE EEE EER EERE EEE E/ 
/* This program finds the shortest path between nodes #/ 
/* in a network. It has 8 internal procedures: */ 
/* SETUP» CONNECT» FIND+ PRINT_ALL» PRINT_PATHS» */ 
/* SHORTEST_DISTANCE» PRINT_ROUTE» and FREE_ALL. */ 
[I EEG EEE / 
network: 
Procedure options(main)§ 
hreplace 
true by ‘1i’bs 
false by ‘O’b» 
citysize by 20, 
infinite by 3276735 
declare 
sysin files 
declare 
1 city_node based» 
2 city_name Character(citysize) varying» 
total distance fixed» 
investigate bit» 
2 city_list pointers 
2 route head pointer 
declare 
1 route node based» 
2 next_city Pointer» 
2 route distance fixed» 
2 route list pointeri 
declare 
city_head pointer 
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do while(true)3 
call setup()i 
if city_head = null then 
stops 
call print_all()3 
call print_paths()i 
call free _all()3 
endi 
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[EEK H HH E EEE EEE EE / 
/* This procedure reads two cities and then calls the */ 
/* procedure CONNECT to establish the connection (in #*/ 
/* both directions) between the cities, */ 
[FE RGGI EI / 
setup: 
Procedure} 
declare 
distance fixed» 
(cityl» city2) character(citysize) varying; 
on endfile(sysin) goto eof 
city_head = null 
Put skip list(‘Type "Cityl» Dist» City25"/)5 
Put skips 
do while(true)3 
get list(cityls distance» city2)3 
call connect(city1l»s distances city2)$ 
call connect(city2+ distances cityl)3 
ends 
eof: 
end setups 


(GEIGER / 
/* This procedure establishes a single route_node to ¥*/ 
/* connect the first city to the second city by */ 
/* calling the FIND procedure twices once for the */ 
/* first city and once for the second city. */ 
1 IR EERIE REE EH / 
onnects: 
Procedure(source city+s distance, destination city) 
declare 
source city character(citysize) varying» 
destination city character(citysize) varying» 
distance fixed» 
(ry s+ d) pointers 


s = find(source city)3 

d = find(destination city)i 
allocate route node set (r)i 
tT->route distance = distance} 
T->next_city = di 

tT->route list = s->route headi 
s->route head = ri 

connecti 
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[| HHH K EEK ER EEE EEE EEE EERE EEE ER EERE EEE EEE / 
/* This procedure searches the list of cities and */ 
/* returns a Pointer to the requested city_node., */ 
[ERIE / 
find: 
Procedure(city) returns(pointer)§ 
declare 
city character(citysize) varying» 
(p+ 9) pointers 


o Pp = city_head 
Tepeat(p->city_list) while(p*=null)3 
if city = p->city_name then 

return(P)3 

endi 
allocate city_node set(P)i 
P->city_ name = citys 
P->city_list = city_headi 
city_head = Pi 
P->total distance = infinite’ 
P->route head = nulls 
return(P)§ 

end finds 


[HHH HEHEHE LEE EEE KEKE EEE REE EE HEE HEHE EERE EE / 
/* This procedure starts at the city head and */ 
/* displays all the cities in the city list. ¥#*/ 
AGGIE / 
Print_all: 
Procedure} 
declare 
(p+ 9) Pointers 


do Pp = city head 
repeat(p->city_ list) while(p*=null)i 
Put skip list(p->city_ names: /)5 
do 4 = P->route head 
repeat(a->route list) while(9*=null)3 
Put skip list(9->route distancer‘miles to’s 
9->next_city->city_name)§ 
end§ 
ends 
end print_alli 
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129 
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148 
149 
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[HERE EHRHREHEER REE EEE EEE EEE EEE EEE RHE H HHH H RHEE H EH HEEE/ 
/* This procedure reads a destination city» calls the #/ 
/* SHORTEST_DISTANCE Procedure» and sets the */ 
/* total_distance field in each city_node to the */ 
/* total distance from the destination city. a 
[EERE ERRERHHES HREKEHRH KE HERR E LEEK ERE RHEL HEHE HERE RHHEE/ 
Tint paths: 
Procedure} 
declare 
city character(citysize) varying; 


on endfile(sysin) goto eof 
do while(true)§ 
Put skip list(‘Type Destination ‘)3 
get list(city)3 
call shortest distance(city)i 
on endfile(sysin) goto eoli 
do while(true)3 
Put skip list(‘Type Start ‘)3$ 
Set list(city)3 
call print _route(city)$ 
end: 
eol: revert endfile(sysin)$ 
ends 
eof: 
end print _paths3 
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[HHH HE KKH ER ELE EERE RHEE EERE EEE HERE EEE EERE H EEE EERE EEE / 
/* This Procedure is the heart of the program, It */ 
/* takes an input citys the destinations and computes */ 
/* the minimum total distance from every city in the */ 
/* network to the destination. It then records this ¥*/ 
/* minimum value in the total_distance field of every */ 
/* city_node. */ 
[HHH HE EE ERK EER EERE EE EEE EEE ERE HE ERE EEE / 
shortest distance: 
Procedure(city)$ 
declare 
city character(citysize) varying$ 
declare 
bestp Pointer» 
(dy bestd) fixed» 
(P+ 9s Pr) Pointers 
do Pp = city_head 
repeat(Pp->city_list) while(P*=null)i 
P->total distance = infinited 
P->investigate = false 
end3 
P = find(city)$ 
P->total distance = 03 
P->investigate = trues 
do while(true)$ 
beste = nulli 
bestd = infinites 
do Pp = city_head 
repeat(p->city_ list) while(p*=null)i 
if p->investigate then 
dos 
if p->total distance < bestd then 
do} 
bestd = p->total distances 
beste = Pi 
ends 
end3 
end$ 
if beste = null then 
returns 
bestr->investigate = falsej 


b 
b 
b 
b 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
c 
d 
d 
d 
d 
d 
c 
c 
c 
d 
d 
d 
e 
e 
e 
f 
f 
g 
| 
| 
g 
f 
e 
d 
d 
d 


Listing 12-4. (continued) 


PL/I Programming Guide 12.3 A Network Analysis Program 


do 9 = bestp->route head 
repeat(a->route list) while(a*=null)i 
r= 9->next_cityi 
d = bestd + 9->route distances 
if d < r->total_distance then 
doi 
r->total distance = di 
T->investigate = true} 
end} 
ends 
endi 
end shortest distance3 


[EKER EHH ELIE HEE HH HEE HEH EEE EERE EEE / 
/* This procedure displays the best route from */ 
/* the input city to the destination. */ 
[| EEK EEE EEE EEE HEE REE EEE EEE HERE EERE EEE / 
Print route: 
Procedure(city)3 
declare 
city character(citysize) varying 
declare 
(pr9) Pointer» 
(tod) fixeds 
P = find(city)$ 
do while(true)i 
t = p->total distances 
if t = infinite then 
doi 
Put skip list(‘(No Connection) ’)3$ 
returns 
ends 
if t = 0 then 
returns 
Put skip list(t»s‘miles remain+s’)$ 
4 = p->route headi 
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do while(4*=null)i 
P = q->next_cityd 
d = 9->route distances 
d + p->total distance then 


t= 
dos 


Put list(ds‘miles to’ sp->city_name) i 
4 = null3 

endi 

else 
4 = 9->route listi 
ndi 
ndi 
nd print_route3 


| HHH EK KIRKE EEE EERIE EE / 
/* This procedure frees all the storage allocated #/ 
/* by the program while processing the network, itd 
[EERE EK KKK EERE EEE EEE EER RE HEE EEE EE EERE / 


free all: 
| Procedure 


declare 
(p+ 4) Pointerd 
do p = city_head 
repeat(p->city_ list) while(p*=null)3 
do s = p->route_ head 
repeat(a->route list) while(a*=null)3 
free g->route nodej 
end3 
free p->city_nodei 
ends 
L_end free alli 


end network 
Listing 12-4. (continued) 
End of Section 12 


References: Sections 3.4, 7.1-7.8, 8.2 LRM 
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Section 13 
Recursive Processing 


Recursive processing occurs when an active procedure calls itself, or is called. by 
another active procedure. There are many programming problems that lend themselves 
to this kind of construct. This section has three such problems. The first two illustrate 
the basic concepts, and the last one uses recursion in a practical problem. 


In a recursive procedure, a CALL statement, or function reference contained in the 
procedure itself, reinvokes the procedure before returning to the first level call. There- 
fore, you must declare all such procedures with the RECURSIVE attribute so PL/I can 
properly save and restore the local data areas at each level of recursive call. 


PL/I places two restrictions on RECURSIVE procedures. First, it passes all procedure 
parameters by value. You cannot return values from a recursive procedure by assign- 
ment to formal parameters. Instead, you can return a functional value or assign values 
to global variables. 


Note: to maintain compatibility with full PL/I, you should not use formal parameters 
on the left of an assignment statement in a PL/I RECURSIVE procedure. 


Second, PL/I does not allow BEGIN blocks in RECURSIVE procedures. However, 
it does allow nested procedures and DO-groups. The examples that follow illustrate 
the proper formulation of RECURSIVE procedures. 

13.1 The Factorial Function 

The classic example of recursion is evaluation of the Factorial function. This function, 
used throughout mathematics, is a good illustration because you can define it by 
iteration and recursion. 


The iterative definition of the Factorial function is 


n! = (n)(n-1)(n-2) ... (2)(1) 
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where n! is the Factorial function, and n is a nonnegative integer. Therefore: 
(n-1)! = (n-1)(n-2) ... (2)(1) 

You can define the Factorial function using the recursive relation: 
n! = n(n-1)! (by definition, 0! = 1) 


Evaluating the Factorial function using either iteration or recursion produces the 
following values: 


0! 
1! 
2! 
3! 
4! 
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Listing 13-1 shows a program called IFACT that computes values of the Factorial 
function using iteration. The variable F is declared as a FIXED BINARY data item 
that accumulates the value of the factorial up to a maximum of 32767. 


Listing 13-2 shows the output from IFACT. IFACT gives the proper value for the 
Factorial function up to 7!, 5040. At this point, the variable F overflows and produces 
improper results, but the output continues. 


Note: PL/I does not signal FIXEDOVERFLOW for binary computations. 


Listing 13-3 shows the program RFACT that performs the equivalent evaluation of 
the Factorial function using recursion. For comparison, RFACT uses the REPEAT form 
of the DO-group to control the test. RFACT declares factorial as a RECURSIVE 
procedure, and calls the procedure at the top level in the PUT statement on line 10. 
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Line 19 contains an embedded recursive call in the RETURN statement. Factorial 
returns when the input value is zero. All other cases require one or more recursive 
evaluations of factorial to produce the result. For example, 3! produces the sequence 
of computations, 


factorial(3) 3* factorial(2) 
factorial(2) 2* factorial(1) 
factorial(1) 1*factorial(0) 
factorial(0) = 1 
1 

2 1 

3 2 1 
producing the value 6. Listing 13-4 shows the output for the recursive factorial eval- 


uation produced by RFACT. The values again overflow beyond 5040 due to the pre- 
cision of the computations. 


[HHH KEKE EE HEHEHE EHR EER EEE EEE / 
/* This program evaluates the Factorial */ 
/* function (n!) using iteration. */ 
[HEE HK EEK KH EEE EEK EEK EE HE EERE EERE EE HEE / 
r—ifact: 
Procedure options(main)3 
declare 
(is nv F) fixeds 


OnNoOouwawWone 


do i O by 15 
F 13 


don ito 1 by -15 
E P Saye Fa 
ends 


Put edit( ‘factorial (‘+sis’)='sF) 
(skips arf(2)5 ar £(7))5 


end§ 
end ifacti 


a 
a 
a 
a 
a 
b 
b 
b 
b 
c 
c 
d 
d 
d 
c 
c 
c 
b 
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A>difact 


factorial( 

factorial( 

factorial( 

factorial( 

factorial( 

factorial( 

factorial( 

factorial 

factorial( 8)= -25216 the values are incorrect 
factorial( 9)= -30336 | from this point on 
factorial(10)= 24320 

factorial(11)= 5376 

factorial(12)= -1024 

factorial(13)= -13312 

factorial(14)= 10240 

factorial(15)= 22528 

factorial(16)= -32768 

factorial(17)= -32768 

factorial(18)= 0 

factorial(19)= 0 


Listing 13-2. Output from the IFACT Program 


[HEHEHE H KEE KEELER EEE EKER EEE HERE EKER EEE HERES / 
/* This Program evaluates the Factorial #*/ 
/* function (n!) using recursion, */ 
[HHH ERK KHER EERE EEK EEE EKER H EERE EERE EEE / 
tfact: 

Procedure options(main)$ 

declare 

i fixed 
do i = 0 repeat(it+1)3 
[ Put skip list(‘factorial(‘si+’)='’sfactorial(i))$ 
end; 
stops 


ee 
WNeK CHOON OUWNRWYN 
vTrvoo oOo oO TF o7OTpP www pw 
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factorial: 
Procedure(i) returns(fixed) recursive 
declare 
i fixed; 
if i = 0 then return (1)5 
return (i * factorial(i-1))3 
nd factorial; 


end rfacts 
Listing 13-3. (continued) 


A>dfact 


factorial ( O)= 1 

factorial ( 1)= 1 

factorial( 2)= 2 

factorial ( 3)= 6 

factorial ( 4)= 24 

factorial ( S)= 120 

factorial ( 6)= 720 

factorial ( 7)= 5040 

factorial ( 8)= -25216  * the values are incorrect 
factorial ( 9)= -30336 | from this point on 
factorial ( 10)= 24320 

factorial ( 11)= 5376 

factorial ( 12)= -1024 

factorial ( 13)= -13312 

factorial ( 14)= 10240 

factorial ( 15)= 22528 

factorial( 16)= -32768 

factorial ( 17)= -32768 

factorial ( 18)= 0 

factorial ( 19)= 0 


Listing 13-4. Output from the RFACT Program 
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13.2 FIXED DECIMAL and FLOAT BINARY Evaluation 


The Factorial evaluation programs here illustrate an important point about arithmetic 
calculations using different data types. Listing 13-5 shows a program called DFACT. 
It is the same recursive evaluation of the Factorial function found in RFACT, but it 
uses the FIXED DECIMAL data with the maximum allowable precision. Listing 13-6 
shows the output from DFACT. The largest value produced by the program is: 


Factorial(17) = 355,687,428,096,000 


At this point, the run-time system signals FIXEDOVERFLOW to indicate that the 
decimal computation has overflowed the maximum 15 digit value. 


Listing 13-7 shows the program FFACT that evaluates the Factorial function using 
FLOAT BINARY data. Listing 13-8 shows the output from FFACT. FFACT can com- 
pute the value of the function beyond 17. PL/I truncates the number of significant digits 
on the right to approximately 7 equivalent decimal digits. Again, FFACT ends when 
the run-time system signals the OVERFLOW condition because the program produces 
an exponent value that cannot be maintained in the floating-point representation. 


la [| EHR K HHH E EHH EERE EEE HEHEHE EEE EERE EERE EERE / 
2a /* This Program evaluates the Factorial function */ 
3a /* (n!) using recursion and FIXED DECIMAL data, */ 
4a [HHH EEE HEE HEHEHE EH EERE EHH EEE EH EEK EERE HERE HEE HEHE / 
5 a-—dfacts 

6 b Procedure oPptions(main) 3 

7b declare 

8 b i fixeds 

9c r—do i = O repeat(it+i)$ 
10's Put skip list(‘Factorial(‘sis’)=’sfactorial(i))$ 
dic Lends 
a stops 

1) 

14 b r—factorial.: 

Sc Procedure(i) returns(fixed decimal(1510)) 
16 ¢ recursive} 

eae declare 

18 ¢c i fixeds 

a 
20 c if i = 0 then return (1)35 
Zi ¢ return (decimal(is15) * factorial(i-1))3 
z2°t Lend factorial; 
23 b 
24 bl_—end dfact; 


Listing 13-5. The DFACT Program 
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Addfact 


Factorial ( 0)= 

Factorial ( 1)= 

Factorial ( 2)= 

Factorial ( 3)= 

Factorial ( Q)= 

Factorial( 5)= 

Factorial ( 6)= 

Factorial ( 7)= 

Factorial ( 8)= 

Factorial ( 9)= 362880 
Factorial ( 10)= 3628800 
Factorial ( 11)= 39916800 
Factorial( 12)= 479001600 
Factorial ( 13)= 6227020800 
Factorial ( 14)= 87178291200 
Factorial ( 15)= 1307674368000 
Factorial ( 16)= 20922789888000 
Factorial ( 17)= 355687428096000 
Factorial ( 18)= 

FIXED OVERFLOW (1) 

Traceback: 0007 019F 0018 0000 # 2809 6874 0355 0141 
A> 


Listing 13-6. Output from the DFACT Program 


[RR IIIT TETHER HEHE / 
/* This program evaluates the Factorial function */ 
/* (n!) using recursion and FLOAT BINARY data. */ 
[EHH HHH EEE ERIE EEE EERE TR EEE EE EEE / 
ffacts 

Procedure options(main) i 

declare 

i fixed 


1 
4 
3 
q 
5 
6 
7 
8 


a 
a 
a 
a 
a 
b 
b 
b 
c 
c 
c 
b 
b 
b 
c 
c 
c 
c 
c 
c 
b 
b 


do i = O repeat(itl)$ 
[ put skip list(‘Factorial(‘»sis’)=‘sfactorial(i))$ 
ends 
StoP3 


factorial: 
Procedure(i) returns(float) recursive 
declare 
i fixed 
if i = 0 then return (1)5 
return (i * factorial(i-1))3 
end factorial; 


end ffacti 


Listing 13-7. The FFACT Program 
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A>dffact 


1,000000E+00 
1,000000E+00 
2.000000E+00 
0,600000E+01 
2.400000E+01 
1,.200000E+02 
0.720000E+03 
0.504000E+04 
4,032000E+04 
3.628799E+05 
3.628799E+06 
3.991679E+07 
4.790015E+08 
0.622702E+10 
0,871782E+11 
1,307674E+12 
2.092278E+13 
3.S556874E+14 
0,640237E+16 
1,216450E+17 
2,.432901E+18 
0.510909E+20 
1,124000E+21 
2.585201E+22 
0.620448E+24 
1.551121E+25 
4,032914E+26 
1,.088887E+28 
3,048883E+29 
0.884176E+31 
2.652528E+32 
0.822283E+34 
2.631308E+35 
0,868331E+37 


Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
Factorial ( 
OVERFLOW (1) 
Traceback: OO6C 13CB 019B 0000 # 8608 0B15 FBS51 0141 
A> 


Sd 
SCWOONOUBHWYNK CHW ONINOUBRWYNK CO 


WNHNNNNNNN SN 
SocMWUODNOUBWN Ke 


WOW WW 
BWN 


Listing 13-8. Output from the FFACT Program 
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13.3 The Ackermann Function 


The PL/I run-time system maintains a 512-byte stack area to hold subroutine return 
addresses and some temporary results. Under normal circumstances, this stack area is 
sufficiently large for nonrecursive and most simple recursive procedure processing. The 
program in this section, however, illustrates multiple recursion using a stack depth 
that can exceed the 512-byte default value. 


The Ackermann function, denoted by A(m,n), comes from Number Theory and has 
the following recursive definition: 


n+1 if m=0, otherwise 
A(m,n) = <A(m—1,1) if n=0, otherwise 
A((m-—1), A(m,n—1)) 


Listing 13-9 shows the ACK program that reads two values for the maximum m 
and, n on line 11, and then evaluates the function for these values. Listing 13-10 shows 
the program interaction. Although the Ackermann function returns a FIXED BINARY 
value, the program uses the built-in DECIMAL function to control the size of the 
converted field in the PUT statements on lines 12, 15, and 17. 


In this example, ACK uses the STACK option on line 7 to increase the size of the 
run-time stack from its default value, 512 bytes, to 2000 bytes. 


Note: the STACK option is only valid with the MAIN option. You must determine 
the value of the STACK option empirically, because the Compiler cannot compute the 
depth of recursion. If the allocated stack size is too small and the stack overflows 
during recursion, the run-time system outputs the message: 


FREE SPACE OVERWRITE 
and then ends the program. 
This kind of multiple recursion processing is CPU intensive. You should experiment 


with some different values for max, and see if you can determine how much stack is 
being used. 
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[EHH EHH EHH EEE REE HEE IK EE ERE EERE EEE / 
/* This Program evaluates the Ackermann function */ 
/* A(mon)+ and increases the size of the stack a7 
/* because of the large number of recursive calls. */ 
[HHH HH EHR EHR HEE EERE EERE EERE EEE EEE HEE EERE EEE / 
ack: 
Procedure orptions(main+sstack(2000))3 
declare 
(msmaxmenemaxn) fixed$ 
Put skip list(‘Type max men: ‘)3 
get list(maxmsmaxn) § 
Put skip 
list(’ ‘y(decimal(n»4) do n=0 to maxn))3$ 
do m = 0 to maxms 
Put skip list(decimal(ms4) 1°: ')5 
do n = 0 to maxnis 
Put list(decimal(ackermann(min) 14))5 
end 
ends 
stops 


OnNOWebpuone 


ackermann: 
Procedure(mren) returns(fixed) recursive; 
declare (mon) fixed 
if m = 0 then 
return(nt1)§ 
if n = 0 then 
return(ackermann(m-1191))35 
return(ackermann(m-1Lsackermann(msn-1)))§ 
end ackermanns 


nd acks 
Listing 13-9. The ACK Program 
A>ack 


Type max mens #395 


Listing 13-10. Interaction with the ACK Program 
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13.4 An Arithmetic Expression Evaluator 


One of the practical uses of recursion is the translation of statements in a high-level 
programming language. This is because most languages are defined recursively. In 
block-structured languages like PL/I for example, DO-groups and BEGIN and PRO- 
CEDURE blocks can all be nested, and the resulting structure lends itself easily to 
recursive processing. 


The next example illustrates how you can use recursion to evaluate arithmetic expres- 
sions. Here is a simple, recursive definition of an arithmetic expression: An expression 
is a simple number, or a pair of expressions separated by a +, —, *, or/, and enclosed 


in parentheses. 


Using this definition, the number 3.6 is an expression because it is a simple number. 
Clearly, 


(3.6 + 6.4) 


is an expression because it consists of a pair of expressions that are both simple numbers, 
separated by a +, and enclosed in parentheses. Also, 


(1.2 * (3.6 + 6.4)) 


is a valid expression because it contains the two valid expressions 1.2 and (3.6 + 6.4), 
separated by a * and enclosed in parentheses. 


Using the definition given above, the sequences, 


3.6 + 6.4 


(1.2 + 3.6 + 6.4) 


are not valid expressions because the first is not enclosed in parentheses, while the 
second is not a pair of expressions in parentheses. 


The preceding definition of an expression is somewhat restricted, but once established, 
you can expand it to include more complex expressions. 
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Listing 13-11 shows an expression evaluation program called EXPR1. The main 
processing takes place between lines 27 and 31 where EXPR1 reads an expression from 
the console and types the evaluated result back to you. Listing 13-12 shows the console 
interaction with EXPR1 where the user enters several properly and improperly formed 
expressions. 


[RRR KR EH EEK EEE EEK EERE EEE HERE HERR EE EEE EE / 
/* This program evaluates an arithmetic exrression */ 
/* using recursion, It contains two procedures, GNT */ 
/* obtains the input expression consisting of separate *#/ 
/* tokens» and EXP that performs the recursive */ 
/* evaluation of the tokens in the input line. */ 
[HRI ET TR RTE TRH EEE EERE EERE EERE EE / 
expression: 
Procedure options(main)$ 
declare 
sysin files 
value float» 
token character(10) varyings 


<= 


endfile(sysin) 
stoPs 


error(1) /*# conversion or signal #/ 

begins 
Put skip list(*‘Invalid Input at ‘+stoken)3 
get skips 
goto restarts 

ends 


1 
2 
3 
4 
5 
6 
v4 
8 
9 
10 
te 
12 
13 
14 
15 
16 
17 
18 
19 
20 


nN 
— 


restart: 


NONNNN 
NOUR WN 


—do while(‘1’b)i 
Put skip(3) list( ‘Type expression: ‘)3 
value = expP()§ 
Put skip list(‘Value is:’svalue)$ 
ends 


QWNWWNN 
QnNr OuoOD 


gnt: 

Procedure} 

get list(token)# 
end gnt3 


w 
f= 


Ow 
ou 
roooaorvroaoeaono no rtrtetrtnononono norte tertw~veteeeoteows Pewee pw 


w 
~ 
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38 b r—eXP: 

33':6 Procedure returns(float binary) recursive; 
40 ¢ declare x float binary 
Qic call gnt()$ 

42 ¢ if token = ‘(’ then 

43 d doi 

44d x = exP()§ = 
45 d call gnt()3 

46 d if token = ‘+’ then 
47 4 [ x = x + exe()i 

48 d else 

49 d if token = ‘-’ then 
50 d zz - exp()§ 
Sid else 

52 d if token = ‘#’ then 
53 d | * expe()§ 
54d else 

55 d if token = ‘/’ then 
56 d [ / expe()§ 

57 d else 

58 d signal error(1)3 
59d call gnt()$ 

60 d if token “= ‘)’ then 
61 d < signal error(1)3 
62 d L—end3 

63 ¢ —else 

64 c¢ x = tokens 

65 c return(x)3 

66 c Lend exp3 

67 b 

68 blond expression 


Listing 13-11. (continued) 


13.4.1 The Exp Procedure 


The heart of the expression analyzer is the RECURSIVE procedure exp. This pro- 
cedure implements the recursive definition given above and decomposes the input 
expressions piece by piece. The GNT, Get Next Token, procedure reads the next element 
or token, a left or right parenthesis, a number, or one of the arithmetic operators in 
the input line. GNT uses a GET LIST statement, so you must separate each token with 
a blank or end-of-line character. 
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On line 41, exp calls GNT. GNT places the next input token into the CHARAC- 
TER(10) variable called token. If the first item is a number, then the series of tests in 
exp sends control to line 64. The assignment to x automatically converts the value of 
token to a floating-point value. Then exp returns this converted value to line 29, where 
EXPR1 stores it into value, and subsequently writes it out as the result of the expression. 


If the expression is nontrivial, then exp scans the leading left parenthesis on line 42, 
and enters the DO-group on line 43. EXPR1 immediately evaluates the first sub- 
expression no matter how complicated, and stores it into the variable x on line 44. 
EXPR1 then checks token for an occurrence of +, —, *, or /. Suppose, for example, 
token contains the * operator. The statement on line 53 recursively invokes the exp 
procedure to evaluate the right side of the expression. Upon return, it multiplies this 
result by the value of the left side that was previously computed. EXPR1 then checks 
the balancing, right parenthesis starting on line 60, and returns the resulting product 
as the value of exp on line 64. 


13.4.2 Condition Processing 


EXPR1 performs condition processing in three places. The first ON-unit, line 15, 
intercepts an end-of-file, CTRL-Z, condition on the input file, and executes a STOP 
statement. The second ON-unit, line 18, receives control if an error occurs during 
conversion from character to floating-point representation at the assignment on line 
64. The ON-unit displays the token in error, and then executes a GET SKIP statement 
to clear the data to the end of the line. It then transfers control to the restart label, 
which prompts for another input expression. 


EXPR1 signals a condition when it encounters an invalid operator or an unbalanced 
expression. If the operator is not a +, —, *, or /, then EXPR1 executes line 58 and 
signals the ON-unit, line 18. Again, the ON-unit displays the error and transfers control 
to the restart label. Similarly, a missing right parenthesis on line 60 triggers the ERROR(1) 
ON-unit to report the error and restart the program. When the program restarts, 
PL/I discards the information on the current level of recursion. 
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A>dexprl 


Type expression: ( 4+ 5,2) 


Value is: 0,920000E+01 


Type expression: 4,5e-1 


Value is: 4,499999E-01 


Type expression: 


Invalid input at & 


Type expression: ( (3+4)- (10/8) ) 


Value is: 0,.,575000E+01 


Type expression: ( 3 * @ ) 


Value is: 1,200000E+01 


Type Expression: “Z 


A> 
Listing 13-12. Interaction with EXPR1 


13.4.3 Improvements 


The expression analyzer requires spaces between tokens in the input line. Recall that 
Section 11.2 contains a more advanced version of GNT. 


We incorporate this expanded version of GNT into the expression analyzer, and 
also change the error recovery mechanism so that now line 27 discards the remainder 
of the current input when restarting the program. Listing 13-13 shows the improved 
version called EXPR2, and Listing 13-14 shows the console interaction with this improved 
expression evaluator. 
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Even in EXPR2 there is room for expansion. First, you can add more operators to 
expand upon the basic arithmetic functions. Also, you can add operator precedence 
and eliminate the requirement for explicit parentheses. Beyond that, you can add 
variable names and assignment statements to turn the program into a BASIC interpreter! 


[EERE HE EHH EH HEE HEE EERE HH EH KEKE EEE EE HERE EE EEE EERE / 
/* This program evaluates an arithmetic expression */ 
/* using recursion. It contains an expanded version #*/ 
/* of the GNT procedure that obtains an expression */ 
/* containing separate tokens. EXP then recursively #*/ 
/* evaluates the tokens in the input line, */ 
[EHH RHEE HEE EEE EEE HEE HEEL EEK EEE EEE EEE EEE EER EERE ES / 


oe 
bi Procedure orptions(main)§ 


“replace 
true by ‘1’b3 


woowowegewewesewv pw 


declare 
sysin file» 
value float» 
(token character(10)» line character(80)) varying 
static initial(‘’)3 


Ro os 
SWODIMDUBUYNKOHWDIYNMH HV FWN 


endfile(sysin) 
Stor) 


error(1) /*# conversion or signal */ 

begins 
Put skip list(‘Invalid Input at ‘»token)$ 
token = ‘‘$ line = ’'§ 
goto restarts 

end3 


WOQUONNN NN 
se ouwoomaonna 


Testart: 


ww 
on 


do while(‘1’b)3 
Put skip(3) list(‘Type expression: ‘)3 
value = exp()3 
Put edit(‘Value is: 
ends 


Wu w 
ous 


‘yualue) (skiprasf(1094))5 


uw 
~N 


b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
21 b 
22 b 
22-6 
24 b 
2a: ¢ 
c 
c 
c 
c 
b 
b 
b 
c 
Cc 
c 
c 
c 
b 


wo 
o 
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gnt: 
Procedure 
declare 
i fixed 


line = substr(linerlength(token)+1)3 
do while(true)$ 
if line = ‘’ then 
get edit(line) (a)i 
i = verify(lines’ ‘)3 
if i = 0 then 
line = ‘’§ 
else 
do3 
line = substr(linesi)s 
i = verify(lines‘0123456789, ‘)35 


if i = 0 then 
i token = line 


else 


if i= 1 then 
i token = substr(linerl+1)$ 
else 
token = substr(linerlsi-1)3 
returns 
ends 
ends 
end gnt3 


b 
c 
c 
c 
c 
c 
d 
d 
d 
d 
d 
d 
d 
e 
e 
e 
e 
e 
e 
e 
e 
e 
e 
e 
e 
d 
c 
b 


Listing 13-13. (continued) 
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Procedure returns(float binary) recursived 
declare x float binarys 
call gnt()3 
if token = ‘(’ then 
doi 


‘- xX = exP()§ 


call gnt()3 
if token = ‘+’ then 
a x = xX + exP()§ 

else 

if token ‘-' then 
x = xX exp()3 

else 

if token = ‘*’ then 
x = xX exp()3 

else 

if token ‘/* then 
x = X exP()3 

else 

signal error(1)3 

call gnt()i 

if token “= ‘)’ then 
signal error(1)3 


Lends 
else 

x = tokens 
return(x)$ 
exes 


end expressions 


Listing 13-13. Expression Evaluator EXPR2 
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A>dexpr2 


Type expression: ( 2 # 14,5 ) 


Value is: 29.0000 


Type expression: ( (2#3) / (4,3-1,5)) 


Value is: 2.1429 


Type expression: 


Invalid Input at 


Type expression: ((2#3) -5) 


Value is: 1.0000 


Type expression: 


Invalid Input at 


Type expression: 
A> 


Listing 13-14. 


(continued) 


End of Section 13 


References: Sections 2.8-2.9, 3.1-3.2, 4.2, 9 LRM 
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Section 14 
Separate Compilation 


All of the programs presented so far are single, complete units, although many contain 
one or more internal procedures. It is often useful to break larger programs into distinct 
modules to be subsequently linked with one another and with the PL/I Run-time 
Subroutine Library (RSL). 


There are two reasons for separately compiling and linking programs in this manner. 
First, large programs take longer to compile. Smaller segments can be independently 
developed, tested, and integrated, requiring less overall compilation time for the entire 
project. A large program can also overrun the memory space available for the Symbol 


Table. 


Second, particular subroutines are useful for your own application programming. 
You can build your own library of subroutines and selectively link them to your 
programs. Having such a library of common subroutines greatly reduces the overall 
development time for any particular program. 


This section presents basic information required to link program segments. It also 
presents an example of a program that is compiled as two separate modules and then 
linked together. 


14.1 Data and Program Declarations 


You can direct separate modules to share data areas by including the EXTERNAL 
attribute in the declaration of the data item. For example, the statement, 


declare x(10) fixed binary externals 


defines a variable named x occupying 10 FIXED BINARY locations, 20 contiguous 
bytes, that is accessible by any other module that uses the same declaration. 


| UOnIaS 
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Similarly, the statement, 


declare 
1 s external, 
2 ¥¢C10) bit¢e8)> 
2 z character(9) varying$ 


defines a structure named s, occupying a 20-byte area that is accessible by any other 
modules that use the same declaration. 


The following list summarizes basic rules that apply to the declaration of external 
data: 


m EXTERNAL data items are accessible in any block in which you declare them. 
The EXTERNAL attribute overrides the scope rules for internal data. 


Initialize an EXTERNAL data item in only one module. Other modules can 
then reference the item. 


Declare all EXTERNAL data areas with the same length in all modules in which 
they appear. 


In the 8080 implementation, EXTERNAL data items must be unique in the 
first six characters because the linkage editing format truncates from the seventh 
character on. In the 8086 implementation, there is no such restriction. 


Avoid using ? symbols in variable names, because this character is used as a 
prefix for names in the RSL. 


Remember that PL/I automatically assigns the STATIC attribute to any EXTER- 
NAL data item. 


14.2. ENTRY Data 


ENTRY constants and ENTRY variables are data items that identify procedure 
names and describe their parameter values. ENTRY constants correspond to external 
procedures, or procedures defined in the main procedure. 
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ENTRY variables take on ENTRY constant values during program execution through 
a direct assignment statement, or an actual-to-formal parameter assignment implicit 
in a subroutine call. 


You invoke a procedure directly through a call to an ENTRY constant, or indirectly 
by calling a procedure constant value held by an ENTRY variable. As with label 
variables, you can also subscript ENTRY variables. 


The program shown in Listing 14-1 illustrates ENTRY data. The ENTRY variable 
f declared on line 8 is an array containing three ENTRY constants. Starting on line 
12, the program initializes the subscripted elements to the constants a, b, and c respec- 
tively. Note that the constant a corresponds to an externally compiled procedure (see 
Listing 3-1a). 


The ENTRY variable called f declared on line 8 contains three elements. Starting 
on line 13, the program initializes the individually subscripted elements to the constants 
sin, g, and h, respectively. 


On line 16, the DO-group prompts for input of a value to send to each function, and 
then on line 19 calls each function once with the invocation, 


f(id (x) 


where the first parenthesis pair defines the subscript, and the second encloses the list 
of actual arguments. 


The declaration of ENTRY constants and ENTRY variables is similar to FILE con- 
stants and FILE variables. PL/I assumes all formal parameters declared as type ENTRY 


to be entry variables. In all other cases, an entry is constant unless you declare it with 
the VARIABLE keyword. 


The following rules apply to external procedure declarations: 


m You can access data items with the EXTERNAL attribute in any procedure 
where they are declared EXTERNAL. 


@ In the 8080 implementation, you must make external procedure names unique 
in the first six characters (see Section 14.1). In the 8086 implementation, there 
is no restriction. 


@ Avoid using the ? symbol in procedure names. 
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Note: in addition, you must ensure that each formal parameter exactly matches the 
actual procedure declaration, and that the RETURNS attribute exactly matches the 


form returned for function procedures. 


la [EE KEEE EHH EEE EEE ERE EEE EH EEE EERE EEE HEHE RHE EEE EEHE / 
Za /* This Program illustrates ENTRY variables and */ 
3a /* constants. */ 
Ga LEHRER KHER EEE EE HEE EEE EEE EEE EEE EERE EHH ERE REE HERE EEE / 
Sa pcall: 

6 b Procedure options(main) 3 

7 70 declare 

8 b f(3) entry(float) returns(float) variable» 
9b a entry(float) returns(float)» 

10 b i fixed» x floats 

ET b 

12 b f(1) = a3 

13° 6 f(2) = b35 
14 6 f(3) = c§ 

15 b 

16 «¢ do i = 1 to 335 

{7'¢ Put skip list(’Type x ‘)3$ 

18 c get list (x)§ 

19 ¢ Put list(’f ‘sie’ d=! of lid(xd)s 
20 ¢ ends 
21 6b StoP3 
22 6b 
23 b ie 
24 ¢ Procedure(x) returns(float)$s /* internal procedure */ 
zo ¢ declare x floats 
4a return(2*x + 1)3 
2? 6 end bs 
28 b 
25 6b Of 
30 ¢ Procedure(x) returns(float)$ /# internal Procedure */ 
US declare x floati 
32.6 return(sin(x))3 
A end cs 
34 6 
35 b end call3 


Listing 14-1. An Illustration of ENTRY Constants and Variables 


14.3 An Example of Separate Compilation 


This section presents an example program of two modules that are compiled sepa- 
rately and then linked together. The two modules are called MAININVT and INVERT, 
and are shown in Listings 14-2 and 14-3, respectively. Compiling each of these modules 
and then linking them together produces a program that interacts with the console to 
produce the solution set for a system of simultaneous equations. 
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To understand how the programs work, first consider the following system of equa- 
tions in three unknowns: 


a-b+c=2 a-b+c=3.5 
atb-—c=0 a+b-c=1 
2a —b = 0 2a —b =-1 


The values, 


a= 1 a = 2.25 
2 and b = 5.50 
ec =3 c = 6.75 


constitute valid solutions to this system of equations, because: 


1-2+3=2 2.25 — 5.50 + 6.75 = 3.50 
1+2-3=0 and 2.25 + 5.50 — 6.75 = 0 
pis See = 0 2*2.25 — 5.50 = 0 


The values 2,0,0 and 3.5,0,0 are called solution vectors for the matrix. The coefficients 
of the matrix are: 


1 -1 1 
1 i =1 
-1 0 


The MAININVT module interacts with the console to read the coefficients and the 
solution vectors for a system of equations. The INVERT module performs the actual 
matrix inversion that solves the system of equations. 


The essential difference between these two modules is found in the procedure heading. 
The maininvt procedure is the main program because it is defined with the MAIN 
option. The invert procedure is a subroutine called by the main program. In Listing 
14-2, the declaration starting on line 15 defines invert as an EXTERNAL entry constant 
that is then called on line 49. 


On line 21, MAININVT declares the parameters for the invert procedure as a matrix 
of floating-point numbers denoted by maxrow and maxcol. Invert is defined with two 
additional FIXED(6) parameters, but does not return a value. 


The invert procedure, shown in Listing 14-3 has three formal parameters called a, 


r, and c. They are defined on line 2 and declared in lines 7 and 8. INVERT takes the 
actual values of maxrow and maxcol, corresponding to the largest possible row and 
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column value, from a %INCLUDE file, as indicated by the + symbols following the 
line number at the left of both listings. 


After you compile both of the modules, link them together with the command: 


A>link invmat=maininvt sinvert 


The linkage editor combines the two modules, selects the necessary subroutines from 
the RSL, and creates the command file, named INVMAT. 


Listing 14-4 shows the interaction with INVMAT. In this sample interaction, the 
user first enters the identity matrix to test the basic operations. The inverse matrix 
produced for this input value is also the identity matrix. 


The user then enters the system of equations shown above, along with two solution 
vectors. The output values for this system are shown under Solutions: and match the 
values shown above. The second set of solutions corresponds to the second solution 
vector input. 


Finally, the user tests INVMAT with an invalid input matrix size, and then ends the 
program by entering a zero row size. 


[HEHEHE EHH HEE EERE EHH EEE EEE EHH HEE EERE HEHE EEK EE EEE HE/ 
/* This Program is the main module in a Program that */ 
/* performs matrix inversion, It calls the entry */ 
/* constant INVERT which does the actual inversion, #*/ 
RAITT IIE IEEE / 
maininyt: 
Procedure options(main) 
“replace 
true by ‘1’by 
false by ‘O’b3 
“replace 
maxrow by 
maxcol by 


oo cvrcmwnonwnep pw 


1 
2 
3 
4 
bs) 
) 
a 
8 
] 
10 


declare 
mat(maxrowsmaxcol) float binary(24)» 
(isdonem) fixed(6)» 
var character (26) static initial 
(‘abcdefghisklmnorarstuvwxyz’)» 
invert entry 
((maxrowsmaxcol) float(24)» fixed(6)» fixed(6))3 


crc cer Cc ccc = 


Put list(‘Solution of Simultaneous Esuations’)$ 


Listing 14-2. MAININVT - Matrix Inversion Main Program Module 
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r—do while(true)$ 
Put skip(2) list(‘Type rows» columns: ‘’)3 
get list(n)§ 
if n = 0 then 
StoPs 


get list(m)$ 
[ n > maxrow ! m > maxcol then 


Put skip list(‘Matrix is Too Large’)3 
else 
doi 
Put skip list( ‘Type Matrix of Coefficients’) 
Put skip3 
do i= 1 tons 
Put list ( ‘Row’ sie’: /)5 
get list((mat(irdJ) do J = 1 to n))5 
ends 


Put skip list(‘Type Solution Vectors’) 

Put skip 

do Jj =n +1 to ms 
Put list(‘Variable‘srsubstr(vared-nol) s*2/)5 
Set list((mat(irs) do i = 1 to n))5 

end§ 


call invert(matonem) 3 
Put skip(2) list( ‘Solutions: ’)$ 
do i = 1 to ni 
Put skip list(substr(varvsiel) s‘=')5 
Put edit((mat(isi) do Jj = 1 to m-n)) 
(€(892))5 


ends 


Put skip(Z2) list(‘Inverse Matrix is’)3 
do i = 1 to ni 
Put skip edit((mat(ir+J) do Jj = m-n+i1 to m)) 
(x(3)s67(8+2) sskip)3 
ends 
end 


ends 
tesa maininuts 


c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
d 
d 
d 
e 
e 
e 
e 
d 
d 
d 
e 
e 
e 
e 
d 
d 
d 
e 
e 
e 
e 
e 
d 
d 
e 
e 
e 
e 
d 
c 
b 
b 


Listing 14-2. (continued) 
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invert: 
Procedure (a+risc)$ 
“replace 
maxvow by 26% 
maxcol by 403 
declare 
(dy a(maxrowsmaxcol)) float binary(24)+ 
(irsdoKeloreoc) fixed binary(6)3 
do i=itonrs 
d = aliol)i 


do..3°= 1-46 6c] 13 
l alird) = alindt1)/d5 


ends 
a(irc) 


a(Kol)3 


do l= ito @ =< 1! 
| a(Kol) = a(Kel+1) - alivl) * di 


end 
a(Krc) = - alirc) * dé 
ends 
end3 
ends 


b 
b 
c 
c 
d 
d 
d 
c 
d 
d 
e 
e 
f 
f 
f 
e 
e 
d 
c 
b 
b 


end invert 


Listing 14-3. INVERT - Matrix Inversion Subroutine 


A>dinumat 
Solution of Simultaneous Equations 


Type rows» columns: 313 
Type Matrix of Coefficients 
Row bee Ya) 

Row 2°20: 2 

Row 2 20-0 


Type Solution Vectors 
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Solutions: 
a= 
be 
c= 


Inverse Matrix is 
0,00 
1,00 
0,00 


Type rows» columns: 3795 
Type Matrix of Coefficients 
Row 1 SY =<1-4 

Row 2:11 -1 

Row 3 22-1 Q 

Type Solution Vectors 


Variable a :2 00 
Variable b :3.5 1 -1 


Solutions: 

a 1,00 

b 2.00 

Cc 3.00 

Inverse Matrix is 
0,50 0.50 0,00 
1,00 1,00 -1,00 
1,50 0.50 -1,00 

Type rows» columns: 4140 

Matrix is Too Large 


Type rows» columns: 0 


A> 
Listing 14-4. (continued) 
End of Section 14 


References: Sections 3.3.2, 5.1-5.4, 8.2 LRM 
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Section 15 
Decimal Computations 


This section explains how PL/I handles decimal computations, stores decimal data, 
and converts data types. Study this material thoroughly because it is vital to under- 
standing commercial processing. 


15.1 A Comparison of Decimal and Binary Operations 


The arithmetic with which we are most familiar uses the decimal number system. 
All operations, such as addition and multiplication, are based on the number ten, and 
involve the digits zero through nine. Computers, however, perform arithmetic opera- 
tions using binary or base 2 numbers. Computers use binary numbers because the 1s 
and Os can be directly processed by the on-off electronic switches found in arithmetic 
processors. 


Most programming languages allow you to write programs that process base 10 
constants and data items in simple and readable forms. Because the programs process 
decimal values, it is necessary to convert values into a binary form on input and back 
to a decimal form on output. This conversion from one type to another can introduce 
truncation errors that are unacceptable in commercial processing. Thus, decimal arith- 
metic is often required to avoid propagating errors throughout computations. 


In most programming languages, you have no control over the internal format used 
for numeric processing. In fact, two of the most popular BASIC interpreters for micro- 
processors differ primarily in the internal number formats. One uses floating-point 
binary, while the other performs calculations using decimal arithmetic. 


PASCAL Compilers generally use floating- and fixed-point binary formats with imple- 
mentation-defined precision, while FORTRAN Compilers always use floating- or fixed- 
point binary. 


COBOL on the other hand, was designed for use in commercial applications where 
exact dollars and cents must be maintained throughout computations. Therefore, COBOL 
processes data items using decimal arithmetic. 
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PL/I gives you a choice between representations, so that you can tailor the data in 
each program to the exact needs of the particular application. PL/I uses FIXED DEC- 
IMAL data items to perform commercial functions, and FLOAT BINARY items for 
scientific processing where computation speed is the most important factor, and trun- 
cation errors are insignificant or ignored altogether. 


The two programs shown below illustrate the essential difference between the two 
data types. 


decimal_comre: binary_comp: 
[ Procedure options(main)3 Procedure options(main)$ 
declare declare 
i fixed» i fixed» 
t fixed decimal(71#2)3 t float binary(24)3 
t = 03 t = 03 
do i = 1 to 100003 do i = 1 to 100003 
i t=% + 3.105 [ t=t + 3.105 
ends ends 
Put edit(t) (7(10+92))5 Put edit(t) (*(10+2))3 
L_end decimal_comes end binary_comp$ 


Both of these programs sum the value 3.10 a total of 10,000 times. The only difference 
between these programs is that DECIMAL COMP computes the result using a FIXED 
DECIMAL variable, while BINARY_COMP performs the computation using FLOAT 
BINARY. 


DECIMAL COMP produces the correct result 31000.00, while BINARY_COMP 
produces the approximation 30997.30. The 2.70 difference is due to the inherent 
truncation errors that occur when PL/I converts certain decimal constants, such as 
3.10, to their binary approximations. DECIMAL_COMP produces the exact result 
because no conversion occurs when using FIXED DECIMAL variables. 


These two programs illustrate a more general problem. Suppose that during a par- 
ticular day, Chase Manhattan Bank processes 10,000 deposits of $3.10. Using a pro- 
gram with FLOAT BINARY data, $3.10 cannot be represented as a finite binary 
fractional expansion. Therefore it is approximated in FLOAT BINARY form as 
3.099999E + 00. Each addition propagates a small error into the sum, resulting in an 
extra $2.70 unaccounted for at the end of the day. 
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There are also situations where decimal arithmetic produces truncation errors that 
can propagate throughout computations. For example, the fraction 1/3 cannot be 
represented as a finite decimal fraction, and thus is approximated as 


03333333 cc: 


to the maximum possible precision. Such errors only occur when explicit division 
operations take place. 


The difficulty with FLOAT BINARY representations is that some decimal constants 
expressed as finite fractional expansions in FIXED DECIMAL cannot be written as 
finite binary fractions. PL/I necessarily truncates these during conversion to FLOAT 
BINARY form. 


There are both advantages and disadvantages in selecting FIXED DECIMAL arith- 
metic instead of FLOAT BINARY. One advantage of FIXED DECIMAL arithmetic is 
that it guarantees there is no loss of significant digits. All digits are considered significant 
in a computation, so that multiplication, for example, does not truncate digits in the 
least significant positions. Another advantage is that FIXED DECIMAL arithmetic 
precludes the necessity for exponent manipulation, and the operations are relatively 
fast when compared to alternative decimal arithmetic formats. 


The disadvantage is that you must keep track of the range of values that arithmetic 
operands can assume because all digits are considered significant. 


15.2 Decimal Representation 


Decimal variables and constants have both precision and scale. The precision is the 
number of digits in the variable or constant, while the scale is the number of digits in 
the fractional part. For FIXED DECIMAL variables and constants, the precision cannot 
exceed 15, and the scale cannot exceed the precision. 


15.2 Decimal Representation PL/I Programming Guide 


You can define the precision and scale of a variable in the variable declaration. For 
example, 


declare x fixed decimal(10+3)3 


declares the variable x to have precision 10 and scale 3. The Compiler automatically 
derives the precision and scale of a constant by counting the number of digits in the 
constant, and the number of digits following the decimal point. For example, the 
constant 


— 324.76 


has precision 5 and scale 2. 


Internally, PL/I stores FIXED DECIMAL variables and constants as Binary Coded 
Decimal (BCD) pairs, where each BCD digit occupies either the high- or low-order 
four bits of each byte. The most significant BCD digit defines the sign of the number. 
A zero denotes a positive number, and a nine denotes a negative number in the 10’s- 
complement form, as described below. Because PL/I always stores numbers into 8-bit 
byte locations, there can be an extra pad digit at the end of the number to align it to 
an even byte boundary. 


For example, PL/I stores the number 83.62 as, 


EOETIESS 


where each digit represents a 4-bit half-byte position in the 8-bit value. PL/I stores the 
leading BCD pair lowest in memory. 


PL/I stores negative numbers in 10’s-complement form to simplify arithmetic oper- 
ations. A 10’s-complement number is similar to a 2’s-complement binary representa- 
tion, except the complement value of each digit x is 9-x. 


To derive the 10’s-complement value of a number, form the complement of each 
digit by subtracting the digit from 9, and add 1 to the final result. Thus, the 10’s 
complement of -2 is formed as follows: 


(9-2)+1=74+1=8 


PL/I adds the sign digit to the number that then appears as the single-byte value: 


| 98 | 
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Look at an example. Suppose you want to add —2 and +3. PL/I represents these 
numbers as follows: 


PL/I ignores the integers beyond the sign digit above, and produces the correct result 
01. In the following discussion, we show negative numbers with a leading - sign, with 
the assumption that the internal representation is in 10’s-complement form. Thus, we 
write the number -2 as: 


There is no need to explicitly store the decimal position in memory, because the 
Compiler knows the precision and scale for each variable and constant. Before each 
arithmetic operation, the compiled code causes the necessary alignment of the operands. 
In later examples, we show a decimal point position to emphasize the effect of alignment. 


For example, the number — 324.76 appears as: 


A 


When PL/I prepares this value for arithmetic processing, it first loads it into an 8- 
byte stack frame, consisting of 15 BCD digits with a high-order sign. In this case, the 
-324.76 is shown as: 


boop p Pe 


In ordinary arithmetic, when beginning each operation you must properly align the 
operands for that operation and, upon completion, you must decide where the resulting 
decimal point appears. 


In PL/I, the Compiler performs the alignment and accounts for the decimal point 


position, but it is useful for you to imagine what is taking place, so you can avoid 
overflow or underflow conditions. In some cases, you might want to force a precision 
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or scale change during the computation using the DECIMAL or DIVIDE built-in 
functions. The sample programs discussed in the following sections give examples of 
these functions. 


15.3 Addition and Subtraction 


In PL/I, addition and subtraction are functionally equivalent. This is because in 
subtraction, PL/I first forms the 10’s complement of the subtrahend and then performs 
the addition. Given two numbers x and y, with precision and scale (p,q) and (r,s), 
respectively, the addition operation proceeds as follows. 


First, PL/I loads the two operands onto the stack and then aligns them by shifting 
the operand with the smaller scale to the left until the decimal positions are the same. 
Given that the scale of x is greater than the scale of y, y is shifted q-s positions to the 
left, with zero values introduced in the least significant positions. 


After alignment, y has precision r+(q—s) and scale q. PL/I signals a FIXED OVER- 
FLOW condition if significant digits are shifted into the sign position during the align- 
ment process. 


Here is a specific example. Suppose x = 31465.2437 and y = 9343.412 so that x 
has precision p = 9 and scale q = 4, while y has precision r = 7 and scale s = 3. 
Before alignment, the numbers appear as: 


p= = 
<q=4> 
+000000314652437 


+000000009343412 


<s=3> 
<—r=7—> 


a 
PL/I Programming Guide 15.2 Decimal Representation 


PL/I aligns y with x by shifting q-s = 4—3 = 1 positions to the left, producing: 


<— p=9-—> 
<q=4> 
+000000314652437 


* 
II 


< 
ll 


+000000093434120 


<qo> 
<r+(q-s) = 8> 


The number of digits in the whole part of x is p-q, while the whole part of y contains 
r-s digits, 


|< pq=s >| 
31465 
9343 
| <rs=4> | 


so the sum must contain p-q = 5 digits in the whole part: 


31465 
+ 9343 


40808 
|< p-q=5 >| 


There is a possibility that some values could produce an overflow, requiring one 
extra digit in the whole part: 
99999 
+ 99999 


199998 
| <(p-q) +1=6> | 
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The total number of digits in the sum of x and y is the number of digits in the whole 
part, (p-q) + 1=6, plus the number of digits in the fraction, given by q, resulting in a 
precision of: 

(pPq)h+1+q=ptil 

Given two values x and y, of arbitrary precision and scale, you can use the specific 
case shown above to derive the form of the resulting precision and scale. First, the 
scale must be the greater of q and s, given by, 

max (q,S) 
and the resulting precision must have max(q,s) fractional digits. 

Second, the whole part of x contains p-q digits, while the whole part of y contains 
r-s digits. The result contains the larger of p-q and r-s digits, plus the fractional digits, 
along with one overflow digit, for a total of, 

max (p-q,r-s) + max (q,s) + 1 
digit positions. 
Because the precision cannot exceed 15 digits, the resulting precision must be, 
min(15,max(p-q,r-s) + max(q,s) + 1) 
digits. 

The precision and scale of the resulting addition or subtraction written as a pair 

(p’,q’) is: 


Li U 


P q 


( min(15,max(p-q,r-s) + max(q,s) + 1), max(q,s) ) 
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Using the preceding example: 


<—\ p=9—> 
<q=4> 
+000000314652437 


* 
ll 


+000000093434120 


< 
ll 


—_q~> 
<rt+(q-s) = 8> 


xt+ty=+000000408086557 


<4 > 
<= 10 —> 


The precision (10,4) shown in the diagram is derived using the expression, 


f 


p’ q 
( min(15,max(9-4,7-3) + max(4,3)+1), max(4,3) ) 
or: 


( min(15,max(5,4)+4+1), 4) = (min(15,10),4) = (10,4) 


15.4 Multiplication 


Evaluating the precision and scale for multiplication is simpler than addition and 
subtraction because PL/I does not have to align the decimal point before the multipli- 
cation. Given two operands x and y with precision and scale (p,q) and (r,s) respectively, 
PL/I multiplies the two operands digit by digit to produce the result. 
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Just as in ordinary hand calculations, the number of decimal places in the result is 
the sum of the scale factors q and s. The total number of digits in the result is the sum 
of the precisions of the two operands. To conform to the PL/I Subset G standard, 
PL/I includes one additional digit position in the final precision. The precision and scale 
of the result (p’,q’) is given by: 


, 


P q 
(min(15,p+r+1),q+s) 


Suppose that x = 924.5 and y = 862.33, with the precision and scale values (4,1) 
and (5,2): 


x= +000000000009245 


y= +000000000086233 


The product of the digits of x and y is shown with the resulting precision and scale, 


x*y=+000000797224085 


<3> 
<—— 10——> 


where PL/I computes the precision and scale as: 
(min(15,4+5+1),1+2) = (min(15,10),3) = (10,3) 
PL/I signals the FIXEDOVERFLOW condition if the product contains more than 
15 significant digits. In the previous section, where x = 31465.2437 and y = 9343.412, 
the product x*y has precision 17, causing FIXEDOVERFLOW. 


In this particular case, you must apply the DECIMAL function to reduce the number 
of significant digits in either x or y. The computation is carried out as, 


DECIMAL(x,9,3) * y 
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which loads the stack with the two following values before the multiplication takes 
place: 


DECIMAL(x,9,3) =|+ 00000031465 243 | 
y =|+ 000000009343412 


The precision and scale of the product is: 
+293992729029116 


<—6—> 
<< 15 ———__> 


PL/I first computes the precision as p+r+1 = 16, and then reduces this to the 
maximum 15 digit precision by: 


min(15,p+r+1) = min(15,16) = 15 


When performing multiplication, it is your responsibility to ensure that the precisions 
of the operands involved do not produce overflow. You can explicitly declare the 
precision and scale of the variables involved in the computation, or apply the DECIMAL 
function to reduce the precision of a temporary result. 


15.5 Division 


Division is the only one of the four basic arithmetic operations that can produce 
truncation errors. Therefore each division operation produces a maximum precision 
value consisting of 15 decimal digits, and a resulting scale that depends upon the scale 
values of the two operands. 


Assuming that x and y have precision and scale (p,q) and (r,s) respectively, and that 
x is to be divided by y, the division operation takes place as follows. 
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First, PL/I shifts x to the extreme left by introducing 15-p zero values on the right, 
leaving the dividend on the stack as: 


<— p—> <—15-p +> 
<< ¢q—= 


PL/I then shifts the decimal point of x right by an amount s to properly align the 
decimal point in the result, producing the following operands: 


_———p Se = 1S 
<q-s > <—15-p—~> 


The significant digits of y then continuously divide the significant digits of x until 
the operation generates 15 decimal digits. 


In the diagram above, the number of fractional digits produced by the division is 
determined by the placement of the adjusted decimal point in x. The field following 
the decimal point contains (q-s) plus (15-p) positions, yielding the following precision 
and scale for the result of the division: 


(15, (q-s)+(15-p)) or (15,15-p+q-s) 


Suppose x = 31465.243, and y = 9343.41, have precision and scale values of (8,3) 
and (6,2), respectively. The value x when loaded on the stack appears as: 


<= 8 — > 


<-3-> 
x= +000000031465243 
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PL/I then shifts the value of x to the extreme left and loads the value of y, producing 
the values: 


<< 8—> <15-8=7> 
K3> 


x = +314652430000000 
y= +000000000934341 
<2> 

ha 


The imaginary decimal points are shifted to the right by two positions to properly 
align the decimal point in the result, producing: 


<— 83—>|<— 7 ->| 
1 


* 
ll 


+314652430000000 


+000000000934341 


< 
ll 


<6 
The six significant digits of y divide the significant digits of x, and the result is: 
Pe, | anne eee 
<1+7=8> 
x/y = + 000000033676401 
In this case, the precision and scale of the result is given by: 
(15,(15-p+q-s) = (15,15-8 + 3-2) = (15,8) 


The most important consideration in decimal division is generating enough digits in 
the fractional part for the computation being performed. This is done in two ways. 


First, when aligning the dividend, PL/I pads with zeros and provides 15-p fractional 
digits. Thus, dividend values with small precision generate more fractional digits. 
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Second, if q is greater than s, then PL/I generates (q-s) additional fractional digits 
as shown above. If on the other hand, the dividend contains fewer fractional digits 
than the divisor, then q is less than s and (s-q) fractional digits are consumed. 


The case of q = s occurs quite often. In this particular situation, the number of 
fractional digits depends entirely upon the precision of the divisor, and results in 
15-p fractional digits. 


You might also want to truncate or extend the result with zeros using the DIVIDE 
built-in function during a particular computation (see the PL/I Language Reference 
Manual, Section 4.2.5). The form of the function is, 


DIVIDE (x,y,p,q) 


where p and q are literal constants. They can appear as an expression or subexpression 
in an arithmetic computation, and have the same effect as the statement: 


DECIMAL (x/y,p,q) 
As before, y divides x, but the precision and scale values are forced to (p,q). PL/I 
carries out the computation as described above, and then shifts the resulting value by 
the appropriate number of digits to obtain the desired precision and scale. 


End of Section 15 


References: Sections 3.1.2, 4.2 LRM 


Section 16 
Commercial Processing 


Commercial applications of PL/I use decimal calculations. The four programs in this 
section illustrate PL/I built-in functions, EDIT formats including Picture, and the method 
of breaking down a complex program into small, logically distinct procedures. 


16.1 A Simple Loan Program 


Listing 16-1 shows the LOAN1 program that computes a loan payment schedule 
using three input values corresponding to the loan principal (P), the yearly interest rate 
(i), and monthly payment (PMT). LOAN1 continuously applies the following algorithm 
until the remaining principal reaches zero, and the loan is paid off. 


The algorithm is: 


1. Each month, increase the starting principal P by an amount fixed by the interest 
rate. 


P= P+ (i * P) 
2. Each month, reduce the remaining principal by the payment amount. 
P = (P + (i * P)) — PMT 


LOAN assumes that the principal does not exceed $999,999,999.99. Thus the 
declaration on line 12 defines P as a FIXED DECIMAL variable with precision 11 and 
scale 2. The payment does not exceed $9,999.99, so PMT is declared as FIXED DEC- 
IMAL with precision 6 and scale 2. Finally, LOAN1 defines the interest rate i as FIXED 
DECIMAL(4,2), allowing numbers as large as 99.99%. The two variables m and y 
correspond to the month and year, beginning at the first month of the first year. 


LOAN1 reads the initial values between lines 17 and 22. In this example, LOAN1 
does not perform any range checking. Thus it can accept negative values, and can 
process payment values that cannot pay off the loan. These checks would have to be 
made in a real application environment. 
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On each iteration, LOAN1 increases the month until it reaches the 12th month, at 
which point the built-in MOD function, line 26, increments the year. LOAN1 then 
displays the current principal P on line 32, and adds the monthly interest on the 
following line. 


LOAN 1 performs the computation on line 33. The variable i has precision and scale 
4(2), while the variable P has precision and scale 11(2). Therefore, the multiplication i 
*P yields a temporary result with precision and scale, 15(4). 


Next the division by the literal constant 1200 is required because the interest rate is 
expressed as a percentage (division by 100) over a one-year period (division by 12). The 
result of the division (i * P)/1200 has precision 15, because the constant 1200 has 
precision and scale, 4(0). PL/I computes precision and scale in division as (15,15-15+ 
4-0). Finally, LOAN 1 uses the built-in function ROUND to round the second decimal 
place, the cents position. 


In the last month, if the remaining principal is less than the payment, LOAN1 
performs the test on line 34. If the test is true, line 35 changes the payment to equal 
the principal. Line 36 prints the payment, and finally, line 37 reduces the principal by 
the payment using the assignment statement: 


P - PMT 


Listing 16-2 shows the output from LOAN1 using an initial loan of $500, interest 
rate of 14%, and payment of $22.10 per month. 
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| EKER HEHE EEE EEE dee / 
/* This program produces a schedule of loan Payments */ 
/* using the following algorithm: if P = loan Payments #*/ 
/* i = interests and PMT is the monthly Payment then a7 
/* P = (P + (i#P) - PMT). */ 
[FIRTH / 
loanl: 

Procedure options(main)$ 

declare 

m fixed binary» 

y fixed binary» 

P fixed decimal(i1s2)+5 

PMT fixed decimal(6+2)+ 

i fixed decimal(4:2)$ 


— 
oWOON OU BWON Ye 


_ 
i 


do while(‘1’b)3 
Put skip list( ‘Principal 
get list (P)3 
Put list(‘Interest ‘)§ 
get list(i)s 
Put list( ‘Payment ‘5 
get list(PMT)3$ 
03 
03 
do while (P > 0)$ 
if mod(ms12) = 0 then 
dos 
| a a ey 
Put skip list( ‘Year’ sy) 
ends 
mem +t 15 
Put skip list (msP)§ 
P = P + round( i * P / 1200+ 2)3 
if P < PMT 
then PMT = P3 
Put list(PMT)3$ 
P = P - PMT$ 
end 
ends 


os 
omMmmoOoN OU BUN 


Ld 
| ed 


23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 


wow wo 
oan 


a 
- oO 


end loanis 
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A>loant 


Principal 500 
Interest 14 
Payment 22.10 


Year 1 

500,00 
483.73 
467.27 
450.62 
433.78 
416.74 
399.50 
382,06 
364.42 
346.57 
328.51 
310.24 


oon ounsaune 


291.76 
273.06 
254.15 
235.02 
215.66 
196.08 
176.27 
156.23 
135,95 
115,44 

94,69 

73,69 


52,45 
30,96 
9.22 
Principal 
A> 


Listing 16-2. Output from the LOAN1 Program 
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16.2 Ordinary Annuity 


Listing 16-3 shows the ANNUITY program. Given the interest rate (i) and two of 
three values, ANNUITY computes either the present value (PV), the payment (PMT), 
or the number of pay periods (n) for an ordinary annuity. 


ANNUITY contains one main loop between lines 35 and 80 which reads the present 
value, payment, and yearly interest from the console. On each iteration, you enter two 
nonzero values and one zero value, then ANNUITY computes the value of the variable 
that you enter as zero. ANNUITY retains the values on each loop so that you can 
enter a comma if you do not want to change the value. In this example, ANNUITY 
does not check that the input values are in the proper range. 


[HR K RR RR EERIE / 
/* This program computes either the present value(PV), #/ 


/* the payment(PMT)» or the number of Periods in an */ 
/* ordinary annuity. */ 
[EHH E HERE EEE EE EEE ER EERE EEE / 
r— annuity: 
Procedure options(main)$ 
“replace 


a 


clear by **2"% 
true by ‘1’b3 

declare 
PMT fixed decimal(712)» 
PY fixed decimal(912)» 
IP fixed decimal(6+6),5 
x float binary» 
yi float binary» 
i float binary» 
n fixed; 


declare 
ftc entry(float binary(24)) 
returns(character(17) varying)$ 


Put list (clears‘*i*iO RD INARY ANNUIT Y‘)3 
Put skip(2) list 
(‘*iEnter Known Values» or O+ on Each Iteration’) 


on error 
begins 
Put skip list(‘*iInvalid Data» Re-enter’) 
goto retry 
end3 


NNNNNNNNN DN &— FY RFF Fe ee ee 
OD IMU BPWOnNnNeK CHO WAI DME HONK CHWOOAOIHFHBUsoceuyne 


uw 
o 


wow 
Nn = 
conononrvoororvorcorveooreoeverveveverververervevevereverevervtenrwnweeweeee 


aw 
wo 


Listing 16-3. The ANNUITY Program 


RY TO DIGITAL RESEARCH 201 


16.2 Ordinary Annuity PL/I Programming Guide 


retry: 

f— do while (true) § 
Put skip(3) list(‘*iPresent Value ‘)3 
get list (PV) 5 
Put list(‘*iPayment 
get list (PMT)$ 
Put list(‘*ilInterest Rate 
Set list(yi)s 
i= yi / 12005 
Put list(‘*iPay Periods 
get list(n)i 


if PV = 0 | PMT = 0 then 
x= 1 - A/(1+ide/n5 


[RRR IIE / 
/* compute the Present value #*/ 
[IEEE / 
if PV = 0 then 
doj 
PY = PMT * dec(ftc(x/i) 11596)35 
Put edit(‘*iPresent Value is ‘’»PV) 
(arp $$$ $$$ 1$$$V,99')5 
ends 


[ HERER HEE E EHH EEE ER HEE EE / 
/* compute the Payment #/ 
[HE HH KKH K ELH HERE ERE EERE / 
if PMT = 0 then 
dos 
PMT = PV # dec(ftc(i/x) 11598)3 
Put edit(‘*iPayment is ‘»PMT) 
(arP$$1$$$ 1$$$V,99') 5 


ends 


[ ERE H EEE HH EKER ER ER EEE RE / 
/* compute number of Periods */ 
[HHH EEE H KEKE HH EEE EERE EER EEE / 
if n = 0 then 
dos 
IP > (tetas 
x = char(PV * IP / PMT)$ 
n = ceil ( - log(t-x)/log(iti) 03 
Put edit(‘*i’snys’ Pay Periods’) 
(aep‘ZZZ9'1a)3 


ends 
“ends 


end annuity 


Listing 16-3. (continued) 
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Listing 16-4 shows an interaction with the ANNUITY program in which several 
different values are used as input. 


A>dannuity 
ORDINARY ANNUITY 


Enter Known Values» or 0» on Each Iteration 


Present Value 32000 
Payment 0 

Interest Rate 8.75 

Pay Periods 360 
Payment is $251.74 


Present Value » 

Payment 0 

Interest Rate » 

Pay Periods 240 

Payment is $282.78 


Present Value 0 
Payment , 
Interest Rate » 
Pay Periods , 

i 


Present Value is $31,998.87 


Present Value 32000 
Payment , 
Interest Rate » 
Pay Periods 0 
240 Pay Periods 


Present Value “C 
A> 


Listing 16-4. Interaction with the ANNUITY Program 


16.2.1 Mixed Data Types 


ANNUITY uses both FLOAT BINARY and FIXED DECIMAL data because it must 
perform a mixture of decimal arithmetic calculations and analytic function evaluations. 
The variables used throughout the program are defined between lines 12 and 18 as 
follows: 


@ PMT holds the payment value, is declared as FIXED DECIMAL(7,2), and can 
be as large as $99,999.99, 
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@ PV holds the present value, is declared as FIXED DECIMAL(9,2), and can be 
as large as $99,999,999.99, 


@ The variable IP holds the interest rate for a one month period, and is declared 
as FIXED DECIMAL with six decimal places. 


@ The variable n holds the number of payment periods, is declared as FIXED 
BINARY, and can range from 1 to 32767. 


@ The variables x, yi, and i are FLOAT BINARY numbers used during the com- 
putations to approximate decimal numbers with 7 decimal places. 


ANNUITY computes the unknown value using the equations shown below, rather 
than the iteration. ANNUITY assumes the interest rate is greater than zero. 


First, the present value is given by: 


1 
1 = 
(1 + i)” (1) 
PV = PMT 
i 
Transposing equation (1) gives: 
i 
PMT = PV 
1 
1 = 
(iL -" (2) 
Finally, solving for n gives: 
i 
Log (1 - PV (--) ) 
PMT 
n= — (3) 
Log (1+ i) 


The following expression appears in both equations (1) and (2): 


1 - 1/(1 + i) *¥ nn 
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Therefore, ANNUITY stores this value in the variable x, line 47, and uses it when 
evaluating PV and PMT. x is only an approximation of the decimal value given 
by this expression. 


16.2.2 Evaluating the Present Value PV 


If you enter a zero value for PV, then ANNUITY executes the DO-group between 
lines 53 and 57, and computes PV as: 


PY = PMT * dec(ftc(x/i) 11596); 


Line 20 declares ftc as an external subroutine. It is part of the PL/I Run-time Sub- 
routine Library (RSL), so ANNUITY only needs to declare it as an entry constant to 
use it. 


The division x/i produces a FLOAT BINARY temporary result that ftc then converts 
from FLOAT to CHARACTER form. For example, suppose that x/i produces the value 
3.042455E+01. Then ftc(x/i) returns 30.42455 which is acceptable for conversion to 
decimal. If PL/I cannot convert the floating-point argument to a 15-digit decimal num- 
ber, ftc signals the ERROR(1) condition, indicating a conversion error. 


Finally, the built-in DECIMAL function is applied to the character string to convert it 
to a specific precision and scale, 15(6). When this is done, the multiplication and 
subsequent assignment to PMT takes place. 


How is this particular value for precision and scale decided? To answer the question, 
first consider a restricted form of the same program, 


declare 
PMT fixed decimal(7+s2)>+ 
PY fixed decimal(9+2) s+ 
Q fixed decimal(ury) 3 
PY = PMT * Q§ 


where you must decide on the appropriate constant values for u and v. 


PV has precision and scale 9(2), and thus there must be seven digits in the whole part 
and two digits in the fraction. PL/I generates the full seven digits in the whole part if the 
product PMT * Q results in any of the precision and scale values: 


(9,2) (10,3) (11,4) (12,5) (13,6) (14,7) (15,8) 
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The assignment to PV truncates any fractional digits beyond the second decimal place. 
Because PMT has precision and scale (7,2), you can choose Q with a precision and scale 
of (15,6). Then the multiplication produces a result with precision and scale, 


(min(15,7+15+1),2+6) = (15,8) 
according to the rules stated previously. 
Given an expression with precision and scale values as shown below, 


a = b * Cc 
(Pq) (r,s) (u,v) 


where p, q, r, and s are constants, you can set the precision and scale of c to: 
u = 15 v= 15 —-(p+q-s) 


Thus, using the values shown in the original program, the precision and scale of Q 
becomes: 


v = 15 — (9 + 2 — 2) = 8, or (uy) = (15,6) 
16.2.3 Evaluating the Payment PMT 

If you enter a nonzero present value for PV and a zero value for the payment PMT, 
then ANNUITY enters the DO-group beginning at line 63 and computes the value of 
PMT as: 


PMT = PY # dec (ftc(i/x) +15+8)3 


The computation uses essentially the same technique as shown in the previous exam- 
ple. You must decide the precision and scale of the second operand in the multiplication. 
You are really concerned only with the value of the scale because the precision can be 
taken as 15. 


Using the analysis shown above, evaluate the form, 


a = b+ c 
(7,2) (9,2) (15,v) 
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and determine the value for v: 
v=15 -(p+q-s) = 15 -(7+2- 2) =8 


16.2.4 Evaluating the Number of Periods n 


When you enter nonzero values for PV and PMT, but set the number of periods to 
zero, ANNUITY executes the DO-group beginning on line 73 to compute n. The 
assignment on line 74 first changes the interest for a monthly period from FLOAT 
BINARY to FIXED DECIMAL. 

Next, the assignment on line 75, 


ke = char(PY @ IP 7 PMT): 


first computes the partial decimal result PV * IP / PMT, then converts the result to 
CHARACTER, and then to FLOAT BINARY through the assignment to x. 


The multiplication PV * IP produces a temporary result with the precision and scale: 


PV «+ )SOP 
(9,2) (7,2) 


(15,4) 


The temporary result is now divided by PMT and results in another temporary result 
with the following precision and scale, 


PV*IP / PMT 
(15,4) (7,2) 


(15,2) 
because, according to the rules for division, 
(15,15 -—p+q-—s) = (15,15-—15+4-2) = (15,2) 


thus providing two decimal places in the computation. 
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The intermediate conversion to CHARACTER form is necessary because otherwise 
PL/I would first convert the intermediate result to FIXED BINARY, and then to FLOAT 
BINARY, resulting in truncation of the fraction. This sequence of conversions is nec- 
essary to maintain compatibility with the full language. 


If required, you could generate additional fractional digits by applying the DECIMAL 
built-in function following the multiplication, 


x = char( dec( PV*P, 11,4 ) / PMT); 
and produce a quotient with precision and scale: 
(15,15-11+ 4-2) = (15,6) 


ANNUITY uses the value x in the expression on line 76 to compute the number of 
payment periods, and applies the CEIL function to the result so that any partial month 
is treated as a full month in the payment period analysis. 


Finally, ANNUITY uses the Picture edit format to write out the values of PV, PMT 
and n. 


16.3 Loan Payment Schedule Format 


The LOAN2 program shown in Listing 16-5 is essentially the same as that presented 
in Section 16.1, but it has a more elaborate analysis and display format. LOAN2 uses 
an algorithm similar to that described in Section 16.1. The main processing occurs 
between lines 101 and 136, where the program increases the initial principal by the 
monthly interest, and reduces it by the monthly payment until the principal becomes 
zero. 


The four listings that follow the discussion of the program show several examples 
of interaction with LOAN2. 


Listing 16-6 shows a minimal display corresponding to a loan of $3000 at a 14% 
interest rate with a payment of $144.03. Assume an inflation rate of 0% with a starting 
payment on 11/80, and end-of-year taxes due in December. 


The display shows the principal, interest in December, monthly payment, amount 


paid toward principal in December, and amount of interest paid in the last month of 
the fiscal year. 
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Listing 16-7 shows another execution using the same values as the first time, but 
using a display level of 1. The output also contains the yearly interest paid on the loan 
for each fiscal year that would be deducted from the taxable income. 


Listing 16-8 uses the same initial values of the previous examples, but provides a 
full display of the monthly principal, interest, monthly payment, payment applied to 
the principal, and interest payment. 


Listing 16-9 also shows the same loan and interest rate with an adjustment in dollar 
value due to inflation. This example assumes the inflation rate of 10%, so that all 
amounts are scaled to the value of the dollar at the time the loan is issued. 


For tax reporting, the display showing the total interest paid at the end of each year 
is not scaled, and thus does not match the sum of the interest paid during the year. If 
we assume a 0% inflation rate, the total loan payment is 3,456.97, taken from the 
previous Output. 


But if we assume an inflation rate of 10%, the total cost of the loan in dollars today 
is, 


2,457.00 
+ 374.25 


2,831.25 


resulting in a net gain of 68.75 over a two year period! 


FEAR TTTTIEIIIEEHEE / 
/* This Program computes a schedule of loan Payments */ 
/* using an elaborate analysis and display format. */ 
/* It contains five internal Procedures: DISPLAY» */ 
/* SUMMARY» CURRENT_YEAR» HEADER» and LINE. */ 
[KEKE KEKE HEHEHE EEE HEHEHE HEHEHE HERE EE HERE REE EERE HHH EERE EE / 
loan2: 
Procedure ortions(main)3 
“replace 
true by ‘1‘be 
false by ‘O‘b» 


\ 


clear by ‘*z*‘3 


ee ee 
ONerK CHOON OU SHON 
ooococcrlectcowmewnwnwewee ww 
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declare 

end bit(1)» 

m fixed binary» 

sm fixed binary» 

¥ fixed binary» 

sy fixed binary» 

fm fixed binary» 

dl fixed binary» 

P fixed decimal(10s2),5 

PY fixed decimal(10+2),5 

PP) fixed decimal(10+2)» 

PL fixed decimal(1012) 5 

PMT fixed decimal(10+2)+ 

PMY fixed decimal(1012)>» 
fixed decimal(1012)5 
fixed decimal(10#2) 4 
fixed decimal(10#2)+5 
fixed decimal(4+2),5 
fixed decimal(4s2),5 
fixed decimal(4s3),5 

ci fixed decimal(15+14), 

fi fixed decimal(7+5)»5 

ir fixed decimal(4:2)3 


declare 
name character(14) varying static initial(‘$con’)» 
outPut filed 


Put list(clears‘*i*iS UMMAR Y OF PAYMENT S‘)$ 


on undefinedfile(output) 
j— begins 
Put skip list(‘*i*icannot write to’sname)i 
goto open outPut3 
end3 


open output: 
Put skip(2) list(**i*iOutput File Name ‘)3 
get list(name)$ 
if name = ‘$con’ then 
[. open file(output) title(‘$con’) print pagesize(0)$ 
else 
open file(output) title(name) Print 


b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
c 
c 
c 
c 
b 
b 
b 
b 
b 
b 
b 
b 
b 
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38 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
7 
76 
ra 
78 
79 
80 
81 
82 


83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
EE) 
100 


on error 
begins 
Put skip list(**i*iBad Input Data» Retry’)$ 
Soto retry 
end 


retry: 
do while(true)s 
Put skip(2) list(‘*i*Princiral 
get list(PV)5 
P = PV; 
Put list(‘*i*ilnterest 
get list(yi)s 
t= 714 
Put list(‘*i*iPayment 
Set list(PMV)§ 
PMT = PMV3 
Put list(‘*i*ixInflation 
Set list(ir)s 
fi = 1 + ir/12003 
ci = 1,003 
Put list(‘*i*iStarting Month 
get list (sm)3 
Put list(‘*i*iStarting Year 
get list(sy)5 


Put list(‘*i*iFiscal Month 
get list(fm)s 
Put edit(‘*i*iDisplay Level 
‘“"i*iYr Results : 0 
2°1¥ 9 Interests. 1 
‘*i*iAll Values : 2 
(skipysa)$ 
get list(dl)3 
if dl <¢ 0: dl > 2 then 
signal error3 
smi 
syi 
03 
03 
if name “= ‘’ then 
Put file(output) pages 
call header()3 


ao nn oacqgcnsaoang°wseoess «6oarnra ni a :e4 nononmeanManmnnanmonmtaanntanntrwrwmaanan a & 
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do while (P > 0)3 
end = falsej 
INT round ( i * P / 1200» 2 )3 
IP IP + INT$ 
PL ‘= P§ 
P P + INT$ 
if P < PMT then 
PMT = P3 
P = P - PMT$ 
PP = PP + (PL - P)§ 
INF = ci 
ci = ci / fii 
if Pact tf @)> 4 fm then 
dos 
Put file(output) skip 
edit( ‘i’ slL00*mty) (arp'99/99')5 
call display(PL # INF+s INT #* INF» 
PMT * INF» PP * INF» IP * INF)$ 
ends 
if m= fm & dl > O then 
call summary()3 
mam + ii 
if m > 12 then 
dos 
m= 15 
yoy if 
if y > 99 then 
y = 03 
endi 
end3 
if dl = 0 then 
[ call line()3 
else 
if “end then 
call summary()§ 
— end retrys 


d 
d 
d 
d 
d 
d 
d 
d 
d 
d 
d 
d 
d 
e 
e 
e 
e 
e 
e 
d 
d 
d 
d 
e 
e 
e 
e 
e 
e 
d 
c 
c 
c 
c 
c 
c 
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1 HHH KEKE EEE EEE EEE EE EER ER EE RE EEE EEE / 
/* This procedure performs the output of the actual */ 
/* Parameters passed to it by the main Part of the */ 
/* program, */ 
[HHH RHEE EHH EHH HEHE KEE EEK EH EERE HEHE ERE HEHEHE HERE E / 
display: 

Procedure(arbiscrdse)§ 

declare 

(arbrordse) fixed decimal(10:2)3 


put file (output) edit 
CVE pee ee Pec edi ee a) 
(a12(2(P*$zz9222 9229.99" sa)» 
P‘$zzz+229.v99'sa))3 
end displays 


[| EHR KEKE HEHEHE KEKE EHR EERE EEE EEE EER EEE EEE EEE / 
/* This procedure computes the summary of yearly */ 
/* interest, */ 
[HEH HEE KEKE EE EEE HEE ERE EEE EE EEE EEE EERE / 
summary: 

Procedures 

end = trues 

call current _year(IP-YIN)§ 

YIN = IP$ 
end summary 


[HHH RRR KEKE HEE ER EE EEE EE TET / 
/* This procedure computes the interest paid during #/ 
/* current year. */ 
[HHH E RHEE EEE ETE Ee / 
current year: 
Procedure(I)3 
declare 
yp fixed binary» 
I fixed decimal(10+2)3 
yP = yi 
if fm < 12 then 
yp = yP - 13 
call line()$ 
Put skip file(output) edit 
(‘t’e*Interest Paid During ‘‘’syps‘-‘*’ eye’ is ‘oTe*i’) 
(aox(15)+2(arP'99’) sare $$$ $$$ 1$$9V,99/ ox (16) sad 
call line()3 
end current yeari 
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[EHH HHH KEK HEHEHE KEE EHH EK EERE ERE E EEE EEE EEE EEE EEE / 
/* This procedure defines and prints out an elaborate */ 
/* header format, */ 
[EHH RRR HEEHEIHKE EEHRH EEE HR EE EK EEK EEE EEE RHEE EE / 
header: 
Procedure 
Put file(output) list(clear); 
call line()3$ 
Put file(output) skip edit 
(‘i’e*L OAN Pua: EON: T So Re AOR ei 
(aex(19))5 
call line()$ 
Put file(output) skip edit 
(‘t’s*Interest Rate’syis'%’s*Inflation Rate’ sirs‘Z/9*i") 
(aex(15) +2(asPp*b99u.99% saex(6)) ox (9) vad 
call line()3$ 
Put file(output) skip edit 
(‘iDate i’s’ Principal t’y*Plus Interesti’s’ Payment i» 
‘Principal Paidi’s‘Interest Paid i’) (a)3 
call line()$ 
end header} 


| 


[HHH KH HEHEHE HEHE EE KLEE HEHEHE ERE EERE EERE EEE EE EERE EEE EE / 
/* This Procedure prints out a series of dashed lines, #/ 
[HR KH E EH EHHH KK EEE EEE EERE HEE HEE HEHEHE HEHEHE RHEE EE EEE / 
line: 

Procedures 

declare 

i fixed bin; 
Put file(output) skip edit 


: i 1 to 4)) (adi 
end lines 


b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
c 
b 
b 
b 


end loan2i 
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16.3.1 Variable Declarations 


Starting on line 14, LOAN2 declares several data items: 


PV present value, initial principal 

yi yearly interest rate 

PMV monthly payment 

ir yearly inflation rate 

sm __ starting month of payment (1-12) 

sy starting year of payment (0-99) 

fm __ fiscal month, end of fiscal year (1-12) 
dl display level (0-2) 


LOAN2 declares the initial principal and payment variables as FIXED DECIMAL 
(10,2), allowing values as large as $99,999,999.99. 


It also allows the yearly interest rate and yearly inflation rate to be as large as 99.99. 


The month and year variables, sm, sy, and fm are FIXED BINARY and LOAN2 
assumes that these variables properly represent month and year values. 


The variable dl is the display level and defines the amount of information LOAN2 
displays during a particular iteration of the program. That is, 0 produces an abbreviated 
display, 1 produces additional information, and 2 gives the full trace. 


LOAN2 also declares several other variables used throughout the program: 


initially set to PV, but changes during execution 

total principal paid 

principal for current line, holds P for display purposes 
payment initially set to PMV; changes during execution 
computed interest during current month 

interest at beginning of current year 

total interest paid 

interest rate, initialized to yi 

percent devaluation of original dollar due to inflation 
current devaluation due to inflation 

factor for computing current inflation 


P and PMT are working variables for the principal and payment, so that the program 
does not destroy the original variables PV and PMV during the computations. If you 
enter a comma for subsequent input requests, LOAN2 retains the previous value. 
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16.3.2 Program Execution 


The program execution begins on line 42 with a clear screen character for the Lear- 
Siegler ADM-3A CRT. This control character is defined in the % REPLACE statement 
on line 12. If you are not using an ADM-3A, you can substitute the proper character 
and recompile the program. 


LOAN2 sets an ON-condition to trap possible errors in the OPEN statement, lines 
54 to 56, and then prompts for the report output filename. LOAN2 initializes the 
variable name to the value $con, and if you enter a comma rather than a file or device 
name, LOAN2 assumes the console as the output device. 


If you enter either a comma or the name $con as the output filename, then the OPEN 
statement, line 54, opens the console with a zero page size. This means that the run- 
time system does not issue any form-feeds at the end of each logical page. Otherwise, 
LOAN2 opens the output file or device as a normal PRINT file so that the run-time 
system places form-feeds into the output file or sends them to the physical output 
device, usually the printer, denoted by $lst. 


The ON condition set at line 58 traps any occurrence of the ERROR condition, 
including ERROR(1), which indicates a data conversion error. LOAN2 also program- 
matically signals invalid data on line 92 if the value of dl is out of range. 


LOAN2 does not contain a complete set of routines for error checking. To make 
the program commercially functional, it should signal errors for all other invalid input 
data items, such as a negative interest rate. Furthermore, out-of-bounds computations 
should signal a FIXED OVERFLOW condition. 


Beginning on line 67, LOAN2 reads a set of input values, and then initializes the 
variables for each set of input values beginning on line 93. The PUT LIST statement 
on line 99 executes a page eject if the output file is not the console. Line 100 then 
prints a page header by calling the HEADER subroutine. You should compare the 
formatting statements in the header subroutine with the output values shown in the 
output listings. 


The main processing takes place in the DO-group beginning at line 101, that executes 
repeatedly until the principal is reduced to zero. The variable end indicates whether 
an end-of-year summary has been printed, line 159, and thus avoids the possibility of 
printing a duplicate summary, line 134. 
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On lines 103 and 104, LOAN2 computes the monthly interest INT for the current 
principal P and sums it in IP. LOAN2 saves the current principal for later display in 
PL, and then adds the monthly interest to the principal. If the payment exceeds the 
remaining principal on line 107, LOAN2 reduces the payment to cover this remainder. 
It then reduces the principal by the payment amount, eventually producing a zero value 
if the original payment is sufficient to pay off the loan. Then on lines 111 and 112 
LOAN2 sums the total principal paid and computes the inflation rate. 


16.3.3. Display Formats 


The decision logic for displaying the current computation is somewhat complicated 
because LOAN2 has three display formats. If it is the last iteration, the principal P is 
zero, you select the full display format, dl > 1, or the current month is the end of the 
fiscal year, m = fm, then LOAN2 writes the current computation between lines 114 
and 118. 


The Picture format p‘99/99’ displays the month and year, where 100*m + y produces 
a four-digit number to match this format. For example, if m = 11 and y = 64, then, 


100 *m + y = 100* 11 + 64 = 1164 
1164 appears as 11/64, when printed using the given Picture format. 
The DISPLAY subroutine actually performs the output function, based upon the six 
actual parameters listed in the CALL statement on line 117. The main program first 


adjusts each argument, by the current inflation rate INF, and then passes it to DISPLAY. 
If the inflation rate is set to 0%, the value of INF is 1.00 at this point in the computation. 


The body of the display subroutine, listed between lines 142 and 151 could be 
included in the line subroutine because there is only one call to display. However, 
display illustrates FIXED DECIMAL parameter passing mechanisms and serves to break 
the program into smaller, more readable, segments. Again, you should compare the 
format specifications in the display subroutine with the actual program output. 


The statement on line 120 then checks for the end of fiscal year, m = fm, and, if 
the display mode is either 1 or 2, LOAN2 prints a yearly interest summary using the 
summary subroutine. Summary in turn, calls the current_year subroutine to write the 
yearly interest paid, IP-YIN. The assignment on line 161 retains the base value for the 
next year’s display in YIN. 
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If the fiscal year does not end in December, fm< 12, current_year splits the interest 
rate payment between two calendar years, yp = y - 1. Again, you could combine 
current_year with the summary subroutine without changing the overall program logic. 


The end of the main loop, between lines 131 and 136, contains statements that 
finalize the report. If you select the abbreviated display format, dl = 0, the CALL 
statement on line 132 invokes LINE and prints a line of dashes to complete the display. 


A 


Otherwise, LOAN2 checks to ensure there have been intervening output lines ( end). If 
there have been, it prints an interest summary on line 130. Finally, control returns to the 
top of the DO-group, and LOAN2 reads additional input parameters. 


A>loan2 
SUMMARY OF PAYMENTS 


Output File Name » 
Principal 

Interest 

Payment 

ZInflation 
Starting Month 
Starting Year 
Fiscal Month 


Display Level 
Yr Results : 
Yr Interest: 
All Values : 


‘Date iPrincipal Plus InterestiPayment Principal PaidiInterest Paid 
112/80:$ 2,890.97:$ 33.73:$ 144.03:$ 219,33: 


112/81;$ 11/479.02:$ 17.26:$ 144.03:$ 1,647,75:$ 
111/82:% 0.00:$ 0.25:$ 31000.00:$ 


Listing 16-6. First Interaction with LOAN2 
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Output File Name 
Principal 
Interest 

Payment 
LInflation 
Starting Month 
Starting Year 
Fiscal Month 


Display Level 
Yr Results : 0 


Yr Interest: 1 
All Values : 2 ! 


'Date ‘Principal {Plus Interest :Payment ‘Principal PaidiInterest Paid: 


Listing 16-7. Second Interaction with LOAN2 
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Output File Name 
Principal 
Interest 

Payment 
LInflation 
Starting Month 
Starting Year 
Fiscal Month 


Display Level 

Yr Results : 0 
Yr Interest: 1 
All Values : 2 2 


Inflation Rate 00.00% 
‘Date iPrincirpal iPlus Interest iPayment ‘Principal PaidiInterest Paid! 


‘11/80i$ 3,000.00; i$ 144,03;$ 109,03'$ 
112/80:% 2,890.97\$% i$ 144,03;$ 219.33; 


1O1/81;$ 2+780,67:1$ 32,44:$ 

'02/81:$ 2+669,08:$ 31.14:$ 132.31! 
(03/B1:$ 2:556,19:1$ 29.82: 162.13: 
104/81:$ 2+441.98:$ 28.49:$ 190.62: 
105/811$ 25326.440:$% 27.14;$ 144,03;$ 790.45:$ 217.76: 
106/81'$ 2+209.551$ 25.78:$ 144.03:$ 908.70: 243,54} 
107/81:$ 2+091.30:$ 24,.40:$ 144,031 1,028.33'$ 267.94; 
10B/B81:$ 1/+971,.67:% 23,00:1$ 144,03:$ 1+149.36'$ 290.94; 
109/81'$ 1,/850.64:% 21.591$ 144,03:$ 1+271.80:$ 

t10/B81'$ 1+728.201% 20.16% 144.03:$ 1,395,.67:$ 

t11/81'% 1/604.331$ 18.72:$ 144.03:$ 1,520.98: 

(12/B81;$ 1+479.021$ 144,03;$ 1,647.75:$% 


101/82'$ 11+352.251$ 15.78:$ 1,776,.00:$ 
102/821$ 14+224.00:$ 14,28:$ 1,905.75:$ 
103/82'$ 1/094,25:$ 12,.77\$ 21037,01;1$ 
104/82:$ 962,99: 11,2318 2+169,.81'$ 
105/82:$ 830.19: 9.69:$ 144,03:$ 21304.15'$% 
106/82:$ 695,.85:$ 8.12'$ 144,03:$ 21440,.06;$% 
107/821$ 559,94/$ 6.53'$ 144,03:$ 21577.561$ 447,07} 
108/82:$ 422,40;$ 4,.93:$ 144,03:$ 2/716,66:$ 452.00! 
109/82:$ 283.34:$ 3.31;$ 144,03:% 2/857,38'$ 455.31: 
110/82;'$ 142.62:$ 1,.66:$ 144,031$ 2:999.751$ 456.97: 
t11/82:$ 0,00:$ 31000.00:$ 456.97: 
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Output File Name 
Principal 
Interest 

Payment 
“Inflation 
Starting Month 
Starting Year 
Fiscal Month 


Display Level 
Yr Results : 
Yr Interest: 
All Values : 


Principal 


t11/801$ 
112/80;1$ 
1O1/B811$ 
102/B11$ 
103/81:1$ 
104/811$ 
105/81:$ 
106/81:$ 
107/B11$ 
108/81:$ 
109/81;$ 
110/81:$ 


t11/B81:$ 
(12/8118 
101/82:$ 
102/82:$ 
103/82:$ 
104/82:$ 
105/82:$ 
106/82:$ 
107/82:$ 
108/82:$ 
108/82:$ 
110/82;$ 


, 


, 


‘Plus Interest! 


3,000,001$ 
2,864,95i\$ 
21:733,.391$ 
21602,35'$ 
21071,83'$ 
21341,851$ 
21212,401$ 
2,083,.60:$ 
1:955,36:$ 
1,829,70:$ 
1,702.581$ 
1,576.11'$ 


30.36:$ 
28,.83:$ 
27.32i$ 
25,81:$ 
24.3118 


1,451,911 
1,326.68:$ 
1+203,.50:$ 
1,079.56:$ 
957.46:$ 
835.87'$ 
714,79: 
594.25:$ 
474.26:$ 
354.84: 
236.02: 
117.80:$ 


11.1718 
9.74:$ 
8.34'$ 
6.93:$ 


Payment 


144,03;$ 
142.73:$ 
141,58: 
140.42:$ 
139.27:$ 
138.12:$ 
136.97:$ 
135.82:$ 
134.66:$ 
133.65:$ 
132.50;$ 
131.35:$ 


130.34:$ 
129,.19:$ 
128.18:$ 
127.03:$ 
126.02:$ 
125.01: 
124,00:$ 
123.00:$ 
121,.99'$ 
120.98:$ 
119,97:$ 
118.96;$ 


Loan Payment Schedule Format 


109,03;$ 
217,35: 
325.29!$ 
432.71: 
539.60:$ 
645,.94'$ 
751,71: 
856,90:$ 
961,48: 
1,066,60:$ 
11170.,051$ 
11272.851$ 


1+376,48; 

1+478,031$ 
1+580.64:$ 
1+680.87:$ 
1,782.38:$ 
1,883,39'$ 
1,983,.87:$ 
2,083.B81'$ 
2/183,.19:$ 
21281,.991$ 
21380,19'$ 
21477,79:$ 


Principal PaidiInterest Paid: 


330.69! 
342.16: 
351.67: 
360.06: 
366.92; 
372.31: 
376.22: 
378.66: 
379.68) 
379.27: 
377.45; 


Listing 16-9. Fourth Interaction with LOAN2 
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16.4 Computation of Depreciation Schedules 


The final example of commercial processing involves evaluating depreciation sched- 
ules. Listing 16-10 shows the program called DEPREC that reads several input values 
and prints a table of output according to one of three different depreciation schedules: 


® straight-line 
® sum of the years 
@ double declining 


The program also accounts for bonus depreciation during the first year, reduction 
in taxable income due to sales tax, and investment tax credit on new or used equipment. 


Listings 16-11 through 16-15 illustrate sample interaction with DEPREC using var- 
ious input parameters. 


16.4.1 General Algorithms 
DEPREC uses the following general algorithms: 


gw Investment Tax Credit (ITC) is assumed to be 10% of the selling price applied to 
the full price of new equipment, or up to $100,000 in the case of used equipment. 
(See the %REPLACE statement, line 11.) 


® Bonus depreciation is assumed to be 10% of the selling price, up to a maximum 
of $2,000. (See lines 12 and 13.) 


@ Under all three depreciation schedules, the amount to depreciate is taken as the 
difference between the selling price, minus the bonus depreciation, and the 
residual value of the equipment. 


@ Under all three schedules, the depreciation value computed for the first year is 


prorated by month through the remainder of the fiscal year, not including bonus 
depreciation. 
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In straight-line depreciation, the amount to depreciate is spread uniformly over 
the number of years in which the depreciation occurs. 


For the sum of the years, the year values are summed starting at 1, through the 
number of years in which depreciation takes place: 


ys=1+2+3+...+ years 


The depreciation is distributed over the total number of years by computing 
years/ys multiplied by the depreciation value for the first year, (years-1)/ys 
multiplied by the remainder for the second year, and so forth, until the last 
year, in which 1/ys multiplied by the remaining depreciation value is taken. 


For double declining, yearly depreciation is computed as the book value divided 
by the number of years, which is then multiplied by 2 for new equipment, or 
1.5 if the equipment is used. 


DEPREC first reads the selling price, residual value, percentage sales tax, the per- 
centage income tax bracket, the number of months remaining in the current fiscal year, 
and the number of years in which to depreciate the equipment. It then asks whether 
the equipment is new or used, and reads the depreciation schedule code for the sub- 


sequent report. 


ed 
PHWNeK TCH WAIN MWUMNBWN KS 


v,oroovoeo oto owe wee 


[KHER KEKE HEHE KE EE EEE HE HK EEE KH EERE EERE HEH / 
/* This program calculates three Kinds of depreciation */ 
/* schedules: straight_lines sum_of_the_years» and */ 
/* double_declining. */ 
[HEHEHE EEE HEHE EEE EKER EEE HEE EEE RHEE EKER EEE ERE E HERE REE EES / 
depreciate: 
Procedure options(main)$ 
“replace 
clear screen by 
indent by 15% 
ITC_rate by «1+ 
bonus rate by «1» 
bonus max by 20003 


va 


za 


Listing 16-10. The DEPREC Program 
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declare 
selling price decimal(8+2), 
adjusted price decimal(8+2)+ 
residual value decimal(812), 
year value decimal(8+2), 
depreciation value decimal(812)» 
total depreciation decimal(812)»5 
book value decimal(812)+ 
tax_rate decimal(312), 
sales_tax decimal(812)» 
tax_bracket decimal(2)» 
FYD decimal(8+2), 
ITC decimal(8+2), 
bonus dep decimal(812)»+ 
months remaining decimal(2)» 
new character(4)» 
factor decimal(2+1)5 
years decimal(2)» 
year sum decimal(3)» 
current_year decimal(2)> 
select sched character(1)3 


declare 
copy_to_ list character(d), 
output file variable» 
(sysprints list) files 


declare 
schedules character(3) static initial (‘syd’)» 
schedule (0:3) entry variables 


schedule (0) errors 

schedule (1) straight lined 
schedule (2) sum_of_years3 
schedule (3) = double declining$ 


open file (sysprint) stream Print pPagesize(0) 
title (‘$con’)$ 
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r- do while(‘1’b)3 
Put list(clear_screens'*i*i*iDerpreciation Schedule’) 
Put skip(3) list(‘*i*iSelling Price? ')5 
get list(selling price)3 
Put list(‘*i*iResidual Value? ‘)3 
get list(residual value)i 
Put list(‘*i*iSales Tax (2)? 
get list(tax_rate)i 
Put list(‘*i*iTax Bracket(%)? 
Jet list(tax_bracket)$ 
Put list(‘*i*iProRate Months? 
get list(months remaining) 3 
Put list(‘*i*iHow Many Years? 
get list(years)3 
Put list(‘*i*iNew? (yes/no) 
get list(new)$ 
Put edit(‘*i*iSchedule:’» 
‘“i*iStraight (s)‘s 
“"i*iSum-of-Yrs (y)‘» 
‘*i*iDouble Dec (d)? ‘) (arskip)3 
Jet list(select sched) 
Put list(‘*i*iList? (yes/no) ‘)3 
get list(cory_to list)3 
if copy_to_ list = ‘yes’ then 
open file(list) stream print title(‘$lst‘)3 
factor = 1.53 
if new = ‘yes’ then 
factor = 2.03 
sales tax = decimal(selling price*tax_rate+12+2)/100+,0053 
if new ‘ves’ i selling price <= 100000.00 then 
ITC = selling_price * ITC_ratei 
else 
ITC = 100000 * ITC_ratei 
bonus dep = selling price * bonus rate$ 
if bonus dep > bonus max then 
bonus dep = bonus maxi 
Put list(clear_screen)$ 
call display(sysprint)é 
if copy_to_ list = ‘yes’ then 
call display(list)3 
Put skip list(‘*i*i*i Type RETURN to Continue’) 
Set skip(2)3 
ends 
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[EER HHH KEE EEE EEE LEE EE HEHE EEE EEE E KEKE EERE HEE EEE EE ERE EE / 
/* This Procedure displays the various depreciation */ 
/* schedules. It calls the appropriate schedule with */ 
/* an index into an array of entry constants, */ 
[EEK HH KE KEKE EHH HEE EEE EHR EEE EEE EEE EEE EEE EERE EEE / 
display: 

Procedure(f)3 

declare 

f files 

output = f3 

call schedule (index (schedulessselect_sched))3 
end displays 


BAGH / 
/* This is a global error recovery routine, #*/ 
[HEE H KKH EEE EEE EE HEE EEK EEE EEE HEHEHE HERR E REESE / 
error: 
Procedure} 
Put file (output) edit(‘Invalid Schedule - Enter s+» y» or d’) 
(pagerscolumn(indent) »x(8) .a)3 
call line()$ 
end errors 


[KEKE KEE EEK EEK EEE HEE KE EKER EH EE HEE EERE EERE EE / 
/* This Procedure computes straight_line depreciation, #/ 
| KEKE HEE KEE EEK EEK EERE HEE EEE HERE EE HEE EER ERE / 
straight line: 

Procedures 

adjusted price = selling price - bonus depi 

Put file (output) edit(‘S TRAIGHT L IN E*) 

(pagercolumn(indent) »x(14) radi 

call header()3 

depreciation value = adjusted price - residual valuej 

book value = adJusted pricei 

total depreciation = 03 


b 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
b 
b 
b 
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133 do current year = 1 to yearsi 

134 year_value = decimal(depreciation value/years+8:2) + .0053 
135 if current year = 1 then 

136 doi 

137 year_value = year value * months remaining / 123 
138 FYD = year_valuei 

139 endi 

140 depreciation value = depreciation value - year value} 
141 total depreciation = total depreciation + year _valuei 
142 book_value = adjusted price - total depreciation 

143 call print_line()§ 

144 ends 

145 call summary()§ 

146 end straight lines 

147 

148 BOGIES IIIA / 

149 /* This procedure computes depreciation based on #/ 

150 /* the sum_of_the_vears, */ 

151 AIT IIE / 

152 sum_of years: 

153 Procedures 

154 adjusted price = selling price - bonus depi 

155 Put file (output) edit(‘SUM OF THE YEARS’) 
156 (Page rcolumn(indent) sx(11)sa)i 

157 call header()3 

158 depreciation value = adjusted price - residual valuei 
159 book value = adjusted pricej 

160 total depreciation = 03 

161 year sum = 0§ 

162 do current_year = 1 to yearsi 

163 year sum = year sum + current _yeari 

164 ends 


Listing 16-10. (continued) 
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do current_year = 1 to years} 
year_value = decimal(derreciation value * 
(years - current_vear + 1)1121:2)/ year_sum + .0053 
if current_year = 1 then 
doi 
year value = year value * months remaining / 123 
FYD = year_valuei 
ends 
depreciation value = depreciation value - year valuei 
total depreciation = total depreciation + year _valuei 
book value = adjusted price - total depreciation: 
call print_line()i 
ends 
call summary()i 
end sum_of_yearsi 


[ERE K EKER E HERE EE EK EERE EE EE EEE EEE EERE REESE / 
/* This procedure computes double_declining #/ 
/* depreciation. */ 
[RHR IKE EER ERE EERE EEE EKER EE ERK EERE EEK / 
double declining: 
Procedure} 
adjusted price = selling price - bonus deps 
Put file (output) edit(‘DOUBLE DECLINING’) 
(page rcolumn(indent) +x(10) 1a)3 
call header()3 
depreciation value = adjusted price - residual valuej 
book value = adjusted prices 
total depreciation = 03 
do current year = 1 to years 
while (depreciation value > 0)3 
year_value = decimal(book value/years:8:2) * factor+,0053 
if current_year = 1 then 
doi 
year_ value = year_value * months remaining / 125 
FYD = year value; 
end3 
if year_value > depreciation value then 
year value = depreciation values 
depreciation value = depreciation value - year _valuej 
total depreciation = total depreciation + year _valuej 
book value = adjusted price - total derpreciations 
call print_line()i 
end3 
call summary()i 
end double declining’ 
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[HEHE EEE E EEE EEK ERE EEE EEK ERE HEE EEE EES / 
/* This procedure prints an output header record. */ 
[ERK HH EEE EEE EEE EERE ERE EE EEE EERE KEE EERE EE / 
header: 
Procedure 
declare 
new_or_used character(5)3 


if new = ‘yes’ then 
new_or_used = ‘ New’ 
else 
new_or_used = ’ Used‘i 
Put file (output) edit( 


‘i‘sselling pricetsales tax»new_or_used» 
residual_value»’ Residual Valuei’» 
‘;/smonths remainings’ Months Left ‘> 
tax_rater‘% Tax’stax_brackets'% Tax Bracket’) 
(2(skipscolumn(indent) sa)» 
2(P‘B$$ $$$ 1$$9.V99' sa)» 


skipscolumn(indent) +a9x(5) 9f (2) pav2(K(2) »P* BOD’ 1a) )§ 


Put file (output) edit( 


Depreciation Depreciation 
For Year Remaining 


(skipscolumn(indent) sa)$ 
end header 


| EHR EEE EHH KEE EEE EERE RE EE EEE EEE / 
/* This procedure prints the current line. */ 
| HEHEHE HHE EEE EE HEE EE EEE EERE EEE EE EERE EEE EE / 
Print_line: 
Procedures 
Put file (output) edit( 
‘“{‘scurrent_year» 
i’ syear_valuer 
' |’ ,depreciation_ value» 
‘ {*ybook value’ i’) 
(skiprcolumn(indent) sarf (2) sAlarp'$z zzz 9229u.99'))3 
end print lined 


‘ ‘ 
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[HHH HR KIRK IIH HHT KTR KH HERE EK EE EEE EE EEE / 
/* This procedure Prints the summary of values for #*/ 
/* each type of depreciation schedule. */ 
TITHE IEEE / 
-— summary: 
Procedures 
declare 
adj ITC decimal(812),+ 
total decimal(812),5 
direct decimal(8+2)3 


call line()$ 
adj_ITC = ITC * 100 / tax_bracketi 
total = FYD + sales tax + adj ITC + bonus deri 
direct = total * tax bracket / 1005 
Put file (output) edit( 
First Year Reduction in Taxable Income 


b 

b 

b 

b 

b 

( 

c 

c 

c 

c 

(. 

c 

c 

c 

c 

c 

c 

c 

c Depreciation 

c Sales Tax sSales_taxys 
c ITC (AdJjusted) sadJ_ITCy 
c Bonus Depreciation sbonus_dep» 
c 
c 
c 
c 
c 
c 
c 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
b 
b 
b 


Total for First Year totals 

Direct Reduction in Tax ‘ sdirect»s 
(2(skipscolumn(indent) sa) »2(4(skipscolumn(indent) sa» 
P‘$2922219229U.,99' +x(3) sa) sskipscolumn(indent) sa))$ 
call line()3 
L_—end summarys 


[KERR ERE TER TR EE RT TERRE EE / 


/* This procedure prints a line of dashes, #/ 
ITE / 


line: 
Procedure} 
Put file (output) edit( 
(skipscolumn(indent) sa)3 


end lines 


end depreciate 
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16.4.2 Selecting the Schedule 


There are two constructs in DEPREC that merit special consideration. 


DEPREC uses an array of ENTRY variables to select one of three schedules. Line 
42 defines the array with a subscript range of zero to three. Lines 46 to 49 initialize 
the individual elements of the array, and allow indirect calls to either the ERROR 
subroutine or one of the depreciation schedule handling subroutines. The actual calls 
to the subroutines occur later in the program. 


The schedule selection takes place on line 74, where DEPREC reads one of the 
characters s, y, or d from the console into the character variable select_sched. Line 93 
then invokes the DISPLAY subroutine which performs the actual dispatch to the sched- 
ule handler with the statement on line 108: 


call schedule (index (schedules+select_sched)) 3 


This particular statement works as follows. Line 43 defines the variable schedules, 
and initializes them to the character string ‘syd’, where each letter corresponds to one 
of the schedule-handling following subroutines: 


syd 
123 


double_declining 
sum_of_years 
straight_line 


Therefore, the statement 


call schedule (index(schedules+select sched)) 5 


is equivalent to, 


call schedule (index(svyd+sselect_sched))i 


and for the valid inputs s, y, or d, produces 1, 2, or 3 respectively. 
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Thus, if select_sched is s, the call statement evaluates to, 
call schedule(1)3 


which calls the subroutine STRAIGHT_LINE. Similarly, an input of y or d evaluates 
to, 


call schedule(2)$ or call schedule(3)3 
producing a call to SUM_OF_YEARS or DOUBLE_DECLINING respectively. 


If the value of select_sched is not s, y, or d, then the INDEX function returns a zero 
value. All invalid character input values produce, 


call schedule(0)$ 
which calls the ERROR subroutine and prints the error message. 


16.4.3 Displaying the Output 
Another construct of DEPREC is the output file variable, defined on line 39. During 
the parameter input phase, DEPREC prompts you with: 


List? (yes/no) 


A yes response sends the output from the program to both the console and the list 
device. 


Line 40 declares two file constants, sysprint and list, to address the console and the 
list device. DEPREC first opens the console file, line 51, using an infinite page length 
to avoid form-feed characters. 
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On any iteration of the main DO-group, if you give an affirmative response on line 
77, DEPREC subsequently opens the list device, line 78. This statement can be executed 
several times during a particular execution of the program, but only the first OPEN 
statement has any effect; PL/I ignores the OPEN statement if the file is already open. 


Line 91 calls the DISPLAY subroutine to compute and display the output report for 
a specific set of input values. DISPLAY has a single actual parameter consisting of the 
file constant sysprint that is defined as the formal parameter f on line 104. Line 107 
assigns the formal parameter to the global variable output. Subsequent PUT statements 
write data to the console, producing the first report. 


On line 92, if the variable copy_to_list has the character value yes, then DEPREC 
calls DISPLAY once again. This time, the actual parameter is list, corresponding to the 
system list device. Thus, the output file variable is indirectly assigned the value list, 
and all PUT statements that reference file output send data to the printer. This results 
in both a soft and hard copy of the report. 


DEPREC uses several different forms of decimal arithmetic. Examine the various 
declarations while cross-checking the output formats with the displayed results. 
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A>derrec 
Depreciation Schedule 


Selling Price? 200000 
Residual Value? 40000 
Sales Tax (%)? 

Tax Bracket(%)? 
ProRate Months? 

How Many Years? 

New? (yes/no) 
Schedule: 

Straight (s) 
Sum-of-Yrs (y) 

Double Dec (d)? 

List? (yes/no) 


DOUBLE DECLINING 


$212,000.00 Used $40,000.00 Residual Value} 
10 Months Left 06% Tax SO% Tax Bracket! 


Derreciation 
Remaining 


35 357.14 122,642.86 162,642.86 
34 1852.04 87,790.82 1275790,.82 
271383.75 60 1407.07 100 +407,.07 
21+515.79 38,891.28 781,891.28 
16,905.27 21,986.01 61,986.01 
13+282.71 8+703,30 481+703.30 
81703,.30 | ' 40 1000.00 


Depreciation 355357.14 
Sales Tax 12+000.00 
ITC (AdJusted) 20 1000.00 
Bonus Depreciation 21000,.00 


Total for First Year 69+357.14 
Direct Reduction in Tax 34,678.57 


Listing 16-11. First Interaction with DEPREC 
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Depreciation Schedule 


Selling Price? 
Residual Value? 
Sales Tax (%)? 
Tax Bracket(%)? 
ProRate Months? 
How Many Years? 
New? (yes/no) 
Schedule: 
Straight (s) 
Sum-of-Yrs (y) 
Double Dec (d)? 
List? (yes/no) 


$2121000.00 New $401:000.00 Residual Value: 
8 Months Left O6% Tax 50% Tax Bracket! 


Depreciation Depreciation 
For Year Remaining 


26+333.33 | 131,666.67 171,666.67 
28+214.29 103,452.38 143,452.38 
18,473.64 84,978.74 124,978.74 
12+139.82 72 1838.92 112,838.92 
71804,17 65 034.75 105,034.75 
4:645.34 60,389.41 100,389.41 
2+156.76 981232.65 | 98 »232,65 


Derreciation 26 1333.33 
Sales Tax 121000,00 
ITC (Adjusted) 40 1000.00 
Bonus Depreciation 21000.00 


Total for First Year 80 1333.33 
Direct Reduction in Tax 40,166.66 


Listing 16-12. Second Interaction with DEPREC 
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Depreciation Schedule 


Selling Price? 310000 
Residual Value? 30000 
Sales Tax (%)? 

Tax Bracket(%)? 
ProRate Months? 

How Many Years? 

New? (yes/no) 
Schedule: 

Straight (s) 
Sum-of-Yrs (y) 

Double Dec (d)? 

List? (yes/no) 


$328,600.00 New $30,000.00 Residual Value: 
12 Months Left O62 Tax 50% Tax Bracket! 


Depreciation Depreciation 
For Year Remaining 


12315200.00 154,800.00 184,800.00 
731920,.00 80,880.00 110,880.00 
44 1352.00 36 1528.00 66 1528.00 
26 »611.20 9,916.80 39 1916.80 

9+916,80 | 30 1000.00 


Depreciation 123,200.00 
Sales Tax 18,600.00 
ITC (AdJusted) 62 1000.00 
Bonus Depreciation 21000,00 


Total for First Year 205 1800.00 
Direct Reduction in Tax 102+900.00 


Listing 16-13. Third Interaction with DEPREC 
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551 Depreciation Schedule 


Selling Price? 
Residual Value? 
Sales Tax (2%)? 
Tax Bracket(%)? 
ProRate Months? 
How Many Years? 
New? (yes/no) 
Schedule: 
Straight (s) 
Sum-of-Yrs (y) 
Double Dec (d)? 
List? (yes/no) 


STRAIGHT LINE 


$328 1600.00 New $30,000.00 Residual Value: 
12 Months Left SOX Tax Brackett 


Depreciation Depreciation 
For Year Remaining 


55 1600.00 222,400.00 | 252 1400.00 
44,480.00 177,920.00 207 1920.00 
35+584,.00 ¢ 1421,336,00 172 1336.00 
28 467.20 113,868.80 143,868.80 
225773.76 : 91,095.04 1211095.04 


Depreciation 55 1600.00 
Sales Tax 18+600,00 
ITC (Adjusted) 62 1000.00 
Bonus Depreciation 21000.00 


Total for First Year 138+200.00 
Direct Reduction in Tax 69+100,.00 


Listing 16-14. Fourth Interaction with DEPREC 


End of Section 16 


References: Sections 3.1, 3.5, 4.2, 11.3 LRM 
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Section 17 
Internal Data Representation 


This section describes how PL/I represents data internally. This knowledge is vital 
when using based variables to overlay storage so you do not destroy adjacent storage 
locations. Knowledge of the internal data representation is also useful when so you 
want to interface assembly language routines with high-level language programs and 
the PL/I Run-time Subroutine Library. 


Note: the discussion in this section applies to the implementation of PL/I for both 8- 
bit and 16-bit processors. 


17.1 FIXED BINARY Representation 


PL/I stores FIXED BINARY data in one of two forms, depending upon the declared 
precision. It stores FIXED BINARY values with precision 1-7 in single-byte locations, 
and values with precision 8-15 in a word (double-byte) location. With multibyte storage, 
PL/I stores the least significant byte first. 


PL/I represents all FIXED BINARY data in two’s complement form, allowing single- 
byte values in the range -128 to + 127, and word values in the range -32768 to + 32767. 


The following figure shows the representation of storage in both single-byte and 
double-byte locations for the values 0, 1, and -1. Each boxed value represents a byte 


of memory, and is shown in both binary and hexadecimal values. 


FIXED BINARY(7) FIXED BINARY(15) 


Figure 17-1. FIXED BINARY Representation 


L| uonraS 
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FIXED BINARY(7) FIXED BINARY(15) 


0000 0001 0000 0000 


FIXED BINARY(7) 


1111 1110 


17.2 FLOAT BINARY Representation 


PL/I stores single-precision floating-point binary numbers in four consecutive bytes. 
The 32 bits contain the following fields: a 23-bit mantissa, a sign bit, and an 8-bit 
exponent. The least significant byte of the mantissa appears first in memory. 


exponent s mantissa 


32 23 22 0 


Figure 17-2. Single-precision Floating-point Binary 


PL/I normalizes floating-point numbers so the most significant bit of the mantissa is 
always 1 for nonzero numbers. Because the most significant bit of the mantissa must 
be 1 for nonzero numbers, PL/I replaces this bit position with the sign. PL/I represents 
a zero mantissa with an exponent byte of 00. 
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In order to make certain kinds of comparisons easier, the binary exponent byte has 
a bias of 80 (hexadecimal), so that 81 represents an exponent of 1 while 7F represents 
an exponent of -1. 


Suppose a floating-point binary value appears in memory as shown in the following 
example: 


00) 00 [4081 | 
Low High 
In this case, the mantissa is a bit stream of the form 
4 0 
0100 0000... 


and the high-order bit equal to zero indicates that the mantissa sign is positive. Nor- 
malizing the number produces the bit stream: 


1100 0000... 


The exponent 81 has a bias of 80, so the binary exponent is 1. This means that the 
binary point is one position to the right, resulting in the binary value 


1 100 0000... 


11 in binary represents 2° 2-1; therefore 1.1 base 2 is equivalent to 1.5 base 10. 


00 00 40 81 


is the floating-point binary representation of the decimal number 1.5. 
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PL/I stores double-precision floating-point binary numbers in eight consecutive bytes. 
The 64 bits contain the following fields: a 52-bit mantissa, an 11-bit exponent with a 


bias of 3FF(hexadecimal), and a sign-bit. 


| s | exponent mantissa 


63 62 51 0 


Figure 17-3. Double-precision Floating-Point Binary 


For example, suppose that a floating-point binary value appears in memory as shown 
in the following: 


_00| 00] 00] 00] 00) CO} 43 | CO 


Low High 


In this case, the mantissa is a bit stream of the form, 
3 @ 0 
0011 1100 0000... 
Normalizing the number produces, 
1001 1110 0000... 
The exponent evaluates as follows: 
C 0 4 
1100 0000 0100 


The high-order bit is 1 so the sign is negative. Ignoring the sign bit yields an exponent 
of, 


4 0 4 
0100 0000 0100 
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which has a bias of 3FF, so the real exponent is, 
404 


— 3FF 
5 


Therefore, the binary number is, 


1001 11 10 0000... 


which is 39.5 in decimal. Thus, the eight-byte value, 
00 00 00 00 00 CO 43 CO 
is the double-precision float-binary representation of the decimal number -39.5. 


17.3. FIXED DECIMAL Representation 


PL/I stores FIXED DECIMAL data items in packed BCD (Binary Coded Decimal) 
form. Each BCD digit occupies a half-byte, or nibble. PL/I stores the least significant 
BCD pair first, with one BCD digit position reserved for the sign. Positive numbers 
have a 0 sign, while negative numbers have a 9 in the high-order sign digit position. 


The number of bytes occupied by a FIXED DECIMAL number depends upon its 


declared precision. Given a decimal number with precision p, PL/I reserves a number 
of bytes equal to: 


FLOOR((p + 2)/2) 


where p varies between 1 and 15. This results in a minimum of 1 byte and a maximum 
of 8 bytes to hold a FIXED DECIMAL data item. 


For example, if you declare the number 12345 with precision 5, then PL/I reserves 
FLOOR((5 + 2)/2) = 3 bytes of storage and represents the number as: 


45 23 01 
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PL/I stores negative FIXED DECIMAL numbers in ten’s complement form. To derive 
the ten’s complement of a number, first derive the nine’s complement and then add 1 
to the result. For example, the number -2 expressed in ten’s complement is, 

(9-2) +1=8 
Adding the sign digit gives, 
98 


If you declare -2 with precision 5, then PL/I represents it as: 


98 99 99 


17.4 CHARACTER Representation 

PL/I stores character data in one of two forms, depending upon the declaration. It 
stores fixed-length character strings, declared as CHARACTER(n) in n contiguous 
bytes, with the first character in the string stored lowest in memory. 

PL/I reserves n+1 bytes for variables declared as CHARACTER(n) VARYING with 
the extra byte holding the character string’s length, ranging from 0 to 254. The max- 
imum length of either type of string is 254 characters. 

As an example, suppose the variable A is declared as CHARACTER(20). The assignment 
A = ‘Walla Walla Wash‘; 
results in the following storage allocation, 


WallabWallabWashxxxx 


where b represents a blank, and x represents an undefined character position. If A is 
declared as CHARACTER(20) VARYING data, PL/I stores the same string as 


10WallabWallabWashxxxx 


where 10 is the (hexadecimal) string length. 
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17.5 BIT Representation 


PL/I represents bit-string data in two forms, depending upon the declared precision. 
It stores bit strings of length 1-8 in a single byte, and bit strings of length 9-16 in a 
word (double-byte) value. PL/I stores the least significant byte of a word value first in 
memory. Bit values are stored left-justified, and if the precision is not exactly 8 or 16 
bits, the bits to the right are ignored. 

The following figure shows the storage for the bit-string constant values ‘1’b, ‘A0’b4, 
and ‘1234’b4 in both single- and double-byte locations. Each boxed value represents 
a byte. 

BIT(8) BIT(16) 
0000 0001 0000 0000/0000 0001 
BIT(8) BIT(16) 
1010 0000 0000 0000/1010 0000 
BIT(8) BIT(16) 
N/A 0011 0100/0001 0010 


Figure 17-4. Bit-string Data Representation 


17.6 POINTER, ENTRY and LABEL Data 


PL/I stores variables that provide access to memory addresses as two contiguous 
bytes, with the low-order byte stored first. POINTER, ENTRY, and LABEL data items 


appear as 


Figure 17-5. POINTER, ENTRY, and LABEL Data Storage 


where LS denotes the least significant half of the address, and MS denotes the most 
significant portion. MS contains the page address, where each memory page is 256 
bytes, and LS contains the offset within the page. 
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17.7 File Constant Representation 


PL/I associates each file constant with a File Parameter Block (FPB). The FPB occupies 
57 contiguous bytes containing various fields, some of which are implementation 
dependent. 


Note: each file declaration causes a static allocation for the associated FPB. When you 
open the file, there is an additional overhead of 50 bytes, including the operating 


system’s FCB and the amount specified for buffer space. The run-time system dynam- 
ically allocates this storage from the free storage area. 


17.8 Aggregate Storage 

PL/I stores aggregate data items contiguously with no filler bytes. Bit data is always 
stored unaligned. Arrays are stored in row-major order, with the rightmost subscript 
varying fastest. 
For example, the declaration 


declare A(2s#212)3 


results in the following storage allocation: 


Figure 17-6. Aggregate Storage 


End of Section 17 


Section 18 
Interface Conventions 


This section describes a standard set of conventions for interfacing PL/I programs 
with assembly language routines and with programs written in other high-level lan- 
guages. This section also describes the mechanism for making direct operating system 
calls using a set of optional subroutines not included in the Run-time Subroutine 
Library. 


18.1 Parameter Passing Conventions 

You can pass parameters between a PL/I program and an assembly language routine 
by loading a register pair with the address of a Parameter Block containing pointer 
values. These pointers in turn lead to the actual parameter values. The number of 
parameters and the parameter length and type must be determined implicitly by agree- 


ment between the calling program and called subroutine. The following figure illustrates 
the concept. The address fields are arbitrary. 


Register pair Parameter Block Actual Parameters 


HL (8080) : 2000: 
1000 


BX (8086) 


Figure 18-1. PL/I Parameter Passing Mechanism 


QI UNDIES 
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The following example illustrates this parameter passing mechanism. Suppose a 
PL/I program uses a considerable number of floating-point divide operations, where 
each division is by a power of two. Suppose also that the iterative loop where the 
divisions occur is speed-critical, and that it is useful to have an assembly language 
subroutine to perform the division. 


The assembly language routine simply decreases the binary exponent of the floating- 
point number for each power of two in the division. Decreasing the exponent effectively 
performs the divide operation without the overhead involved in unpacking the number, 
performing the general division operation, and repacking the result. During the division, 
the assembly language routine can produce underflow, and must signal the UNDER- 
FLOW condition to the PL/I program if this occurs. 


The following three listings show programs that demonstrate parameter passing. 
Listing 18-1 shows the program DTEST, which tests the division operation. Listing 
18-2 shows DIV2.ASM, the 8080 assembly language subroutine that performs the 
division. On line 8, DTEST defines DIV2 as an external entry constant with two 
parameters: a FIXED(7) and a floating-point binary value. Listing 18-3 shows 
DIV2.A86, which is the same subroutine in 8086 assembly language. 


On each iteration of the DO-group, DTEST stores the test value 100 into f (line 13), 
and passes it to the DIV2 subroutine (line 14). At each call to DIV2, DTEST changes 
the value of f to f/(2**i) and prints it using a PUT statement. At the point of call, 
DIV2 receives two addresses that correspond to the two parameters i and f. 


Upon entry, DIV2 loads the value of i to the accumulator, and sets the appropriate 
register pair to point to the exponent field of the input floating-point number. If the 
exponent is zero, DIV2 returns immediately, because the resulting value is zero. 


Otherwise, the subroutine loops at the label dby2 while counting down the exponent 
as the power of two diminishes to zero. If the exponent reaches zero during this counting 
process, DIV2 signals the UNDERFLOW condition. 


In DIV2, the call to ?signal demonstrates the assembly language format for param- 
eters that use the interface. The ?signal subroutine is part of the PL/I Run-time Sub- 
routine Library (PLILIB.IRL). 


This subroutine loads the appropriate register pair with the address of the Signal 
Parameter List, denoted by siglst. The Signal Parameter List, in turn, is a Parameter 
Block of four addresses leading to the signal code sigcode, the signal subcode sigsub, 
the filename indicator sigfil (not used here), and the auxiliary message sigaux that is 
the last parameter. 
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The auxiliary message can provide additional information when an error occurs. 
The signal subroutine prints the message until it either exhausts the string length (32, 
in this case), or it encounters a binary 00 in the string. 


Listing 18-4 shows the abbreviated output from this test program. The loop counter 
i becomes negative when it reaches 128, but the DIV2 subroutine treats this value as 
an unsigned magnitude value; thus UNDERFLOW occurs when i reaches — 123. 


a [| ERIE KEKE EEE HEHE EEE HEE EEE ERE HEE ERE EERE EEE EEE EE / 
a /* This program tests an assembly language routine to #/ 
a /* do floating-Point division, */ 
a [| EERE ERE R RHEE E RHEE EERE EEE EEE EE / 
arp—dtest: 

b Procedure options(main)$ 

b declare 

b div2 entry(fixed(7)»sfloat)» 

b i fixed(7)»s 

b f floats 

b 
c do i = O by 13 

c f = 1003 

c call div2(isf)3 

c Put skip list(‘100 / 2 ##’sis*='of)3 

c ends 

b 
b 


1 
2 
3 
4 
) 
6 
F 
8 
9 
10 
11 
12 
13 
14 
15 
16 
L7 
18 


Lonita dtests 


Listing 18-1. The DTEST Program 
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title ‘division by Power of two‘ 
Public div2 
extrn ?signal 
entry: 
Pl -> fixed(7) power of two 
P2 -> floating-point number 


pl -> (unchanged) 
P2 -> P2 / (2*#P1) 
jHL = .low(. Pl) 

mov em jlow(.pl) 
inx h sHL = «high(.pl) 
mou dsm iDE = .Pl 
inx sHL = .low(P2) 
ldax ja = pl (Power of two) 
mov jlow(.P2) 
inx sHL = »high(.P2) 
mov iDE = .P2 
xchg sHL = .P2 


Power of 2» HL = .low byte of frp num 
ito middle of mantissa 
ito high byte of mantissa 
ito exponent byte 


5P2 already zero? 
jreturn if so 


jcounted power of 2 to zero? 
jreturn if so 
jcount Power of two down 
scount exponent down 

dby2 jloop again if no underflow 


Listing 18-2. DIV2.ASM Assembly Language Program (8080) 
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sunderflow occurred» signal underflow condition 
lxi hesiglstisignal parameter list 
call ?signal ssignal underflow 
ret inormally» no return 


dseg 
siglst: dw sigcod iaddress of signal code 
dw sigsub jaddress of subcode 
dw sigfil iaddress of file code 
dw sigaux ijaddress of aux message 
j end of Parameter vectors start of params 
sigcod: db a 503 = underflow 
sigsub: db 128 jarbitrary subcode for id 
sigfil: dw 0000 ino associated file name 
sidgaux: dw undmsgs $0000 if no aux message 
undmsg: db 32,‘Underflow in Divide by Two’:0 
end 


Listing 18-2. (continued) 


Routine to divide single precision float value by 2 


cseg 
Public div2 
extrn ?signalinear 


entry: 
Pl -> fixed(7) power of two 


P2 -> floating Point number 


pl -> (unchanged) 
P2 -> PZ / (2##P1) 


3BX +low(,pl) 
si+lbx] 5SI = «pl 
bx »20bx] 5BX = .P2 
al sAL = Pl (Power of 2) 


Power of 2+ BX = .low byte of frp num 


byte ptr 30bx],0 ip2 already zero? 
done exit if so 


Listing 18-3. DIV2.A86 Assembly Language Program (8086) 
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siglst 


i | 

sigcod 
sigsub 
sisfil 
sigaux 
undmsg 


Parameter Passing Conventions 


or 
iz 

dec 
dec 
nz 


idivide 


byte ptr 3fbx] 
dby2 


by two 
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jcounted power of 2 to zero? 
jreturn if so 

jcount Power of two down 
jcount exponent down 

sloop again if no underflow 


Underflow occurred» signal underflow condition. 


mov 
call 
ret 


dseg 
dw 
dw 
dw 
dw 


bxroffset siglstisignal parameter list 
jsignal underflow 
jnormally» no return 


?signal 


offset sigcod 
offset sigsub 
offset sisfil 
offset sigaux 


end of parameter vector» 


db 
db 
dw 
dw 
db 


end 


3 

128 

0000 

offset undmsg 


jaddress 
jaddress 
jaddress 
jaddress 


of 
of 
of 
of 


signal code 
subcode 
file code 
aux message 


start of Params 

403 = underflow 
jarbitrary subcode for id 
ino associated file name 
50000 if no aux message 
32,‘Underflow in Divide by Two’10 


Listing 18-3. 


TION PRESENTED 


(continued) 


) HERE IS PROPRIETAR 
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1,000000E+02 
3, 000000E+01 
2.S00000E+01 
1,250000E+01 
0.625000E+01 
3.125000E+00 
1,.562500E+00 
0.781250E+00 
3.906250E-01 
1,953125E-01 
0,.976562E-01 


Aa) ee, a OR, ey 
NNN NNN NN NN 
SCWON DU BSW NK OO 


fas 


** 127 0,587747E-36 
** -128 2.938735E-37 
** -127 1,469367E-37 
#* -126 0,734683E-37 
* -125 3,673419E-38 
100 ** -124 1,836709E-38 
100 ** -123 0,918354E-38 
100 / 2 ** -122 4,591774E-39 
UNDERFLOW (128)+ Underflow in Divide By Two 
Traceback: O17F 0118 

A> 


100 
100 
100 
100 
100 


SS, fe, SR Se, Se 


Listing 18-4. DTEST Output (abbreviated) 


18.2 Returning Values from Functions 


As an alternative to returning values through a Parameter Block, PL/I has subroutines 
that produce function values that are then returned directly in the registers or on the 
stack. This section shows the conventions for returning data as functional values. 
References to 8086 registers are in parentheses. 
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18.2.1 Returning FIXED BINARY Data 


Functions that return FIXED BINARY data items do so by leaving the result in a 
register, or register pair, depending upon the precision of the data item. 


PL/I returns FIXED BINARY data with precision 1-7 in the A(AL) register, and data 
with precision 8-15 in the HL(BX) register pair. It is always safe to return the value 
in HL(BX), and copy the low-order byte to A(AL) so register A(AL) is equal to register 
L(BL) upon return. 


18.2.2 Returning FLOAT BINARY Data 


PL/I returns single-precision floating-point numbers as four contiguous bytes on the 
stack. The low-order byte of the mantissa is at the top of the stack, followed by the 
middle byte, then the high byte. The fourth byte is the exponent of the number. 


For example, PL/I returns the value 1.5 as: 


(low stack) —> 


a 


SP 


PL/I returns double-precision floating-point numbers as eight contiguous bytes on 
the stack. The low-order byte of the mantissa is at the top of the stack. The exponent 
occupies three nibbles: the eighth byte, and the high-order nibble of the seventh byte. 


For example, PL/I returns the value — 39.5 as: 


[ 00[00]00[00[00|Co]43]Co | (low stack) —> 


SP 
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18.2.3 Returning FIXED DECIMAL Data 


PL/I returns FIXED DECIMAL data as 8 contiguous bytes on the stack. The low- 
order BCD pair is at the top of the stack. The number is represented in nine’s com- 
plement form, and sign-extended through the high-order digit position, with a positive 
sign denoted by 0, and a negative sign denoted by 9. 


For example, PL/I returns the decimal number —2 as: 


98 99] 99|99 9 99 99/99, (low stack) —> 


SP 


18.2.4 Returning CHARACTER Data 


PL/I returns CHARACTER data items on the stack, with the length of the string in 
a register. For example, PL/I returns the string 


‘Walla Walla Wash’ 
as shown in the following diagram: 


(8080) 


leet ee tow se —> 


(8086) 


A 


SP 


where register contains the string length 10 (hexadecimal), and the Stack Pointer SP 
addresses the first character in the string. 


18.2.5 Returning BIT Data 


PL/I returns bit-string data in a register, or register pair, depending upon the precision 
of the data item. 


PL/I returns bit strings of length 1-8 in the A(AL) register, and bit strings of length 
9-16 in the HL(BX) register pair. Bit strings are left justified in their fields, so the BIT(1) 
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value true is returned in the HL(BX) register as 80 (hexadecimal). It is safe to return 
a bit value in the HL(BX) register pair and copy the high-order byte in A(AL), so 
register A(AL) is equal to register H(BH) upon return. 


18.2.6 Returning POINTER, ENTRY, and LABEL Variables 


PL/I returns POINTER, ENTRY, and LABEL variables in the HL(BX) register pair. 
When returning a label variable that can be the target of a GOTO operation, the 
subroutine containing the label must restore the stack to the proper level when control 
reaches the label. 


The following program listings illustrate the concept of returning a functional value. 
Listing 18-5 shows the program called FDTEST that is similar to the previous floating- 
point divide test. However, FDTEST includes an entry definition for an assembly 
language subroutine called FDIV2 that returns the result on the stack. Listing 18-6 
shows FDIV2.ASM in 8080 assembly language, and Listing 18-7 shows FDIV2.A86, 
the same routine in 8086 assembly language. 


FDIV2 resembles the previous subroutine DIV2 with some minor changes. First, 
FDIV2 loads the input floating-point value into the BC(CX) and DE(DX) registers so 
that it can manipulate a temporary copy and not affect the original input value FDIV2 
then decreases the exponent field in register B(CH) by the input count, and returns it on 
the stack before executing the PCHL instruction. 


ta [HE EE EH HIER EEE EEE HEE HEH EEE EEE E HEH ERE / 
Za /* This Program tests the assembly language routine */ 
3 a /* called FDIV2 which returns a FLOAT BINARY value. #/ 
4a | ERR R HERE HH E EEE HE KERR H HEHEHE EEE EEE EEE EEE / 
Sa fdtest: 

6 b Procedure orptions(main)$ 

7b declare 

8b fdiv2 entry(fixed(7)sfloat) returns(float)»s 

oh i fixed(7)» 
10 b f floati 
11 'b 
2c do i = 0 by 13 
13 -¢ Put skip list(‘100 / 2 ##’sis*=’sfdiv2(i»100))3 
14 c¢ end3 

15 b 

16 b end fdtest3 

Listing 18-5. The FDTEST Program 
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title ‘div by power of two (function) ’ 
Public fdiv2 
extrn ?sisnal 
entry: 

pl -> fixed(7) power of two 

P2 -> floating-point number 
exit: 

pi -> (unchanged) 

PZ -> (unchanged) 
stack: p2 / (2 #* Pl) 

jHL = .low(.Pl) 

mov erm jlow(.p1) 
inx h sHL = shigh(.Pl) 
mou dsm sDE = .pl 
inx $HL = .low(P2) 
ldax ja = pl (power of two) 
mov jlow(,P2) 
inx jHL = shigh(.P2) 
mov sDE = .P2 
xchg sHL = .P2 


— we ee ee ee ee eee 


Power of 2+ HL = .low byte of fP num 
erm iE low mantissa 
h jto middle of mantissa 
dym 3D = middle mantissa 
sto high byte of mantissa 
5C = high mantissa 
sto exponent byte 
3B = exponent 
3B = 00? 
jbecomes 00 if so 
fdret jto return from float div 
by two 
a jcounted power of 2 to zero? 
dz fdret jreturn if so 
der a jcount Power of two down 
der b jcount exponent down 
nz dby2 jloop again if no underflow 
’ 
sunderflow occurred» signal underflow condition 
lxi hesiglstisignal parameter list 
call ?signal isignal underflow 
lxi b10 sclear to zero 
LS d10 sfor default return 


Listing 18-6. FDIV2.ASM Assembly Language Program (8080) 
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POP jrecall return address 
Push b jsave high order fr num 
Push ssave low order fp num 
Pchl jreturn to calling routine 


dseg 
siglst: dw sigcod jsaddress of signal code 
dw sigsub jaddress of subcode 
dw sigfil saddress of file code 
dw sigaux jsaddress of aux message 
5 end of Parameter vectors start of Params 
sigcod: db 3 403 = underflow 
sigsub: db 128 sarbitrary subcode for id 
sigfil: dw 0000 sno associated file name 
sigaux: dw undmsg $0000 if no aux message 
undmsg: db 32,s‘Underflow in Divide by Two’+0 
end 


Listing 18-6 (continued) 


Division by Power of two (function) 


cseg 
Public fdiv2 
extrn ?signalsnear 


entry: 
Pl -> fixed(7) Power of two 
p2 -> floating Point number 


pl -> (unchanged) 
P2 -> (unchanged) 
P2 / (2 ## PI) 


$BX = .low(.Pl) 
sirslbx] iSI = .pl 
al sAL = Pl (Power of 2) 
bx »+20bx] 3BX = .P2 


Power of 2» BX = .low byte of fP num 


dx fbx] 3DX = low and middle mantissa 
exs20bx] sCL = high mantissa» CH = exponent 
chech sexPonent zero? 

fdret jto return from float div 


Listing 18-7. FDIV2.A86 Assembly Language Program (8086) 
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idivide by two 
or alsal scounted Power of 2 to zero? 
Jz fdret jreturn if so 
dec al tcount Power of two down 
dec ch scount exPonent down 
Jnz dby2 sloop again if no underflow 


Underflow occurred» signal underflow condition 


bxrsoffset siglstisignal parameter list 

?signal jsignal underflow 

CX +Cx jclear result to zero for default return 
dx »cx 


POP bx srecall return address 
Push ex ssave high order fp num 
Push dx ssave low order fP num 
Jmp bx jreturn to calling routine 
dseg 
siglst dw offset sigcod jaddress of signal code 
dw offset sigsub jaddress of subcode 
dw offset sisfil saddress of file code 
dw offset sigaux jaddress of aux message 
j end of Parameter vector, start of Params 
sigcod db | 303 = underflow 
sigsub db 128 jarbitrary subcode for id 
sigfil dw 0000 ino associated file name 
sigaux dw offset undmsg 30000 if no aux message 
undmsg db 32,‘Underflow in Divide by Two’ s0 


end 


Listing 18-7. (continued) 


18.3 Direct Operating System Function Calls 


You can have direct access to all the operating system functions through the optional 
subroutines in assembly language programs which are included in source form on your 
PL/I sample program disk. The sample program disk also contains the file REL- 
NOTES.PRN which describes these assembly language programs and several PL/I pro- 
grams that test the various function calls. 


The subroutines in these programs are not included in the standard PLILIB.IRL file 
because specific applications might require changes to the system functions that either 
remove operations to decrease space, or alter the interface to a specific function. If the 
interface to a function changes, you must change the entry point to avoid confusion. 
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Note: be careful when you use these entry points instead of the normal PL/I facilities. 
For example, if you use the MEMPTR function to effect memory management, be 
aware that PL/I uses the dynamic storage area for processing RECURSIVE procedures 
and file I/O buffering. There is no guarantee that the dynamic storage area will not be 
used for other purposes as addtional facilities are added to PL/I. 


Also, when you use the various file maintenance functions, such as DELETE(#19) 
or RENAME (#23), do not access a file that is currently open in the PL/I file system. 
Simple peripheral access, as shown in these examples, is generally safe because no 
buffering takes place. 


End of Section 18 


Section 19 
Dynamic Storage and Stack 
Routines 


This section describes some functions in the PL/I Run-time Subroutine Library (RSL) 
that perform dynamic memory management and manipulate the stack size. 


19.1 Dynamic Storage Subroutines 


The RSL includes a number of functions that provide access to the dynamic storage 
routines. These routines maintain a linked list of all unallocated storage. Upon request, 
these routines search for the first available segment in the free list that satisfies the 
request size, remove the requested segment, and return the remaining portion to the 
free list. If the storage is not available, the run-time system signals ERROR(7), Free 
Space Exhausted. 


PL/I dynamically allocates storage upon entry to RECURSIVE procedures, when 
processing explicit or implicit OPEN statements for files performing disk I/O, or when 
processing an ALLOCATE statement. PL/I always allocates an even number of bytes 
or whole words, no matter what the request size. 


19.1.1 The TOTWDS and MAXWDS Functions 


It is often useful to find the amount of storage available at any given point while 
the program is running. The TOTWDS (Total Words) and MAXWDS (Max Words) 
functions provide this information. 


You must declare the functions in the calling program as: 


declare totwds entry returns(fixed(15))35 
declare maxwds entry returns(fixed(15))5 
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When you invoke the TOTWDS subroutine, it scans the free storage list and returns 
the total number of words (double bytes) available. The MAXWDS subroutine returns 
the size (in words) of the largest contiguous segment in the free list. A subsequent 
ALLOCATE statement that specifies a segment size less than or equal to MAXWDS 
does not signal ERROR(7), because at least that much storage is available. 


Both TOTWDS and MAXWDS count in word units, so the returned values can be 
held by FIXED BINARY(15) counters. Both TOTWDS and MAXWDS return the value 
-1 if they encounter invalid link words while scanning the free space list. This is usually 
due to an out-of-bounds subscript or pointer store operation. Otherwise, these functions 
return a nonnegative integer value. 


19.1.2 The ALLWDS Subroutine 


The PL/I Run-time Subroutine Library contains a subroutine, called ALLWDS, that 
you use to control the dynamic allocation size. You must declare the subroutine in the 
calling program as: 


declare allwds entry(fixed(15)) returns(Pointer) 3 


The ALLWDS subroutine allocates a memory segment in words equal to the size 
given by the input parameter, and returns a pointer to the allocated segment. If no 
segment is available, ALLWDS signals the ERROR(7) condition. The input value must 
be a nonnegative integer. 

Listing 19-1 shows the ALLTST program which is an example of how to use the 
TOTWDS, MAXWDS, and ALLWDS functions. Listing 19-2 shows a sample inter- 
action with the ALLTST program. 
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Onounsuonre 


[HHH HRI HR TRE RE REET TREE EEE / 
/* This program tests the TOTWDS» MAXWDS» and ALLWDS */ 


/* functions from the Run-time Subroutine Library, */ 
[| HEHEHE EK EI EEE HEHE EEE EEE EEE EERE EEE EEE EEE / 


alltst: 
Procedure 
declare 
totwds 
maxwds 
allwds 


declare 
allreq 
memptr 
meminx 
memory 


options(main)§ 


entry returns(fixed(15))» 
entry returns(fixed(15))»5 
entry(fixed(15)) returns(pointer)3 


fixed(15)»+ 

Ptry 

fixed(15)5 

(0:0) bit(16) based(memptr)$ 


while(‘1‘b)3 
Put edit (totwds()+* Total Words Available’, 


maxwds()+* Maximum Segment Size’»s 
‘Allocation Size? ‘) (2(skipsf(6) +a) sskipsa)3 


get list(allrea)i 


memptr 


= allwds(allrea)3 


put edit(‘Allocated’sallreay’ Words at ‘sunspec (memptr)) 


(skiprarf(6) sarbd)§ 


/* clear memory as example #/ 


memory(meminx) = ‘O000‘Db4s 


[" meminx = 0 to allreq-135 


ends 
end3 


end alltsts 


Listing 19-1. The ALLTST Program 
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A>dalltst 


24470 Total Words Available 
24470 Maximum Segment Size 
Allocation Size? 0 


Allocated 0 Words at 2806 
24468 Total Words Available 
24468 Maximum Segment Size 

Allocation Size? 100 


Allocated 100 Words at 28DA 
24366 Total Words Available 
24366 Maximum Segment Size 

Allocation Size? 500 


Allocated 500 Words at 29A6 
23864 Total Words Available 
23864 Maximum Segment Size 

Allocation Size? 23865 


ERROR (7)» Free Space Exhausted 
Traceback: O16D 
A> 


Listing 19-2. Interaction with the ALLTST Program 


19.2 The STKSIZ Function 


In PL/I, the program stack is placed above the code and data area, and below the 
dynamic storage area (TPA). The default size of the program stack is 512 bytes, but 
can be changed using the STACK(n) option in the main procedure heading. 


The STKSIZ (Stack Size) function returns the current stack size in bytes. This function 
is particularly useful for checking possible stack overflow conditions, or in determining 
the maximum stack depth during program testing. 


You must declare the STKSIZ function in the calling program as: 


declare stkKsiz returns(fixed(15))35 
Listing 19-3 shows an example of the STKSIZ function in the program called ACKTST, 


where it checks the maximum stack depth during RECURSIVE procedure processing. 
Listing 19-4 shows an interaction with this program. 
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| EHH EH EEE EERE IEEE ERE ERE REE / 
/* This program tests the STKSIZ function while */ 
/* evaluating a RECURSIVE procedure, */ 
[ER REITER TEETER HEHE / 


ack: 
[ Procedure options(mainsstack(2000))3 
declare 

(mon) fixeds 

(maxmemaxn) fixeds 

nealls decimal(6)» 

(curstack, stacksize) fixed» 
stksiz entry returns(fixed)§ 


put skip list(‘Type max mens ‘)5 
get list(maxmsmaxn) § 
r—do m = 0 to maxms 
do n = 0 to maxns 
nealls = 03 
curstack = 03 
stacksize = 03 
Put edit(*’Ack(*sms’s’ons')="sackermann(men) + 
nealls+’ Calls+’+sstacksizer’ Stack Bytes’) 
(skiprar2(f (2) sa) of (6) of (7) sash (4) radi 


On Oe ee 
WNrK CHoWMB I DOWMBEHONK CHW ONYNaunsuon- 


bo 
P—) 


ends 
L-endi 
stops 


mmm nh 
oraoawn 


p—ackermanns 
procedure(min) returns(fixed) recursived 


nm 
wo 


wa 
=) 


wo 
rae 


declare 
(mon) fixeds 
nealls = ncalls + 13 
curstack = stksiz()3 
if curstack > stacksize then 
stacksize = curstack? 
if m = 0 then 
return(nt+1)3 
if n = 0 then 
return(ackermann(m-191))3 
| return(ackermann(m-L+rackermann(ms+n-1)))3 
end ackermann$ 


oa ack: 


PEFEWWUWHWWWWW 
me COCHoOoODdNIoOuUSwWhN 


ons 
o&W 


Listing 19-3. The ACKTST Program 
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Avacktst 
Type max min: 646 


Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 
Calls» 


Ack( O» O)= 
Ack( O+ 1)= 
Ack( O»+ 2)= 
Ack( 0+ 3)= 
Ack( O» 4)= 
Ack( 0» 5)= 
Ack( O+ 6)= 
Ack( 1+ O)= 
Ack( 1+ 1)= 
Ack( 1+ 2)= 
Ack( 1+ 3)= 
Ack( 1» 4)= 
Ack( 1» S)= 
Ack( 1» 6)= 
Ack( 21 0)= 
Ack( 25 1)= 
Ack( 2 2)= 
Ack( 2+ 3)= Calls» 
Ack( 21 4)= t1 Calls» 
Ack( 21 5)= 13 90 Calls» 
Ack( 25 6)= 15 119 Calls» 
Ack( 35 0)= P) 15 Calls» 
Ack( 35 1)= 13 106 Calls» 
Ack( 3s 2)= 29 541 Calls,» 64 
Ack( 31 3)= 61 2432 Calls» 128 
Ack( 3» 4)= 125 10307 Calls» 256 
Ack( 3+ 5)= ’ 


NUWODONYIODWESHONAYHBDUMNSWNe 
— did 
SOWoaonNoOoOSBNKrY Kr Ke re ee 


oN 
ao~n 


co 
NN Fe ee Be eRe 
OnNwseooOMrnNOCAWAMASLSLSHKHSKS 


n 

Lou) 
wow 
5° 


Ore 
Nn oO 


Listing 19-4. Output From the ACKTST Program 


End of Section 19 
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Section 20 
Overlays 


This section describes how to use the linkage editor to create PL/I overlays. Overlays 
are programs comprised of separate files. The advantage of overlays is that they share 
the same memory locations, so you can write large programs that run in a limited 
memory environment. 


20.1 Using Overlays in PL/I 


In both the 8080 and 8086 implementations, the size of the Transient Program Area 
(TPA) determines the upper limit on the size of a program. However, there is another 
constraint in the 8086 implementation. Although there can be enough memory space 
available on the system, the Compiler generates code that assumes the Small memory 
model. The Small model means that when you link one or more OBJ files with the 
Run-time Subroutine Library (RSL), the size of the code and data sections in the CMD 
are each limited to 64K. Thus, the Compiler determines the upper limit on the size of 
any program, but the size limit is not encountered until link time. 


With modular design, you can write a large program that does not need to reside 
in memory all at once. For example, many application programs are menu-driven, in 
which the user selects one of a number of functions to perform. Because the functions 
are separate and invoked sequentially, they do not need to reside in memory simul- 
taneously. When one of the functions is complete, control returns to the menu portion 
of the program, from which the user selects the next function. Using overlays, you can 
divide such a program into separate subprograms that can be stored on disk and loaded 
only when required. 


OZ uoNDaS 
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The following figure illustrates the concept of overlays. Suppose a menu-driven 
application program consists of three separate user-selected functions. If each function 
requires 30K of memory, and the menu portion requires 10K, then the total memory 
required for the program is 100K, as shown in Figure 20-1a. However, if the three 
functions are designed as overlays, as shown in Figure 20-1b, the program requires 
only 40K, because all three functions share the same memory locations. 


Function 
3 


30K 
Function 30K 
2 100K t 
30K Function Function Function 
1 
ee 30K 40K 
20-1a. Without Overlays 20-1b. Separate Overlays 


Figure 20-1. Using Overlays in a Large Program 


You can also create nested overlays in the form of a tree structure, where each overlay 
can call other overlays up to a maximum nesting level that the Overlay Manager 
determines. Section 20.3 describes the command line syntax for creating nested overlays. 
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Figure 20-2 illustrates the tree structure of overlays. The top of the highest overlay 
determines the total amount of memory required. In Figure 20-2, the highest overlay 
is SUB4. This is substantially less memory than would be required if all the functions 
and subfunctions had to reside in memory simultaneously. 


Figure 20-2. Tree Structure of Overlays 


20.2 Writing Overlays in PL/I 


There are two ways to write PL/I programs that use overlays. The first method 
involves no special coding, but has two restrictions. The first restriction is all that 
overlays must be on the default drive; the second is that the overlay names must be 
determined at translation time and cannot be changed at run-time. 


The second method requires a more involved calling sequence, but does not have 
either of the restrictions of the first method. 
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20.2.1 Overlay Method One 


To use the first method, you declare an overlay as an entry constant in the module 
where it is referenced. As an entry constant, the overlay can have parameters declared 
in a parameter list. The overlay itself is simply a PL/I procedure or group of procedures. 


For example, the following program is a root module with one overlay: 


root: 
Procedure options(main)s 
declare 
ovlayl entry(character(15))35 
Put skip list(‘root’)$ 
call ovlavyi( ‘overlay 17)3 
end roots 


The overlay OVLAY1.PLI is defined as follows: 


ovlayi: 
Procedure(c)3$ 
declare 
c character(15)3 
Put skip list(c)3 
end ovlaylis 


Note: when passing parameters to an overlay, you must ensure that the number and 
type of the parameters are the same in both the calling program and the overlay. 


When the program runs, ROOT first displays the message ‘root’ at the console. The 
CALL statement then transfers control to the Overlay Manager. The Overlay Manager 
loads the file OVLAY1 from the default drive and transfers control to it. 


When the overlay receives control, it displays the message ‘overlay 1’ at the console. 
OVLAY/1 then returns control directly to the statement following the CALL statement 
in ROOT. The program then continues from that point. 


If the requested overlay is already in memory, the Overlay Manager does not reload it 
before transferring control. 
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The following constraints apply to overlay method one: 


m The label in the call statement is the actual name of the overlay file loaded by the 
Overlay Manager; consequently, the two names must agree. 


@ The name of the entry point to an overlay need not agree with the name used 
in the calling sequence, but using the same name avoids confusion. 


@ The Overlay Manager only loads overlays from the drive that was the default 
when the root module began execution. The Overlay Manager disregards any 
changes in the default drive that occur after the root module begins execution. 


@ The names of the overlays are fixed. To change the names of the overlays, you 
must edit, recompile, and relink the program. 


® No nonstandard PL/I statements are needed. Thus, you can postpone the deci- 
sion on whether or not to create overlays until link time. 


20.2.2 Overlay Method Two 


In some applications, you might want to have greater flexibility with overlays, such 
as loading overlays from different drives, or determining the name of an overlay from 
the console or a disk file at run-time. 


To do this, a PL/I program must declare an explicit entry point into the Overlay 
Manager, as follows: 


declare Povlay entry(character(10) sfixed(1))3 


This entry point requires two parameters. The first is a 10-character string that 
specifies the name of the overlay to load, and an optional drive code in the standard 
format (d:filename). 


The second parameter is the Load Flag. If the Load Flag is 1, the Overlay Manager 


loads the specified overlay whether or not it is already in memory. If the Load Flag is 0, 
the overlay manager loads the overlay only if it is not already in memory. 
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Using this method, the example illustrating method one appears as follows: 


roots 
Procedure options(main) $3 
declare 
Poulay entry(character(10)+fixed(1))+ 
dummy entry(character(15))+» 
name character(10)3 


Put skip list(‘root’)3 

name = ‘OV1’$ 

call Povlay(name+s0)3$ 

call dummy( ‘overlay 17)5 
end roots 


The file OV1.PLI is the same as the previous example. 
At run-time, the statement 


call Povlay(name+0)3 


directs the Overlay Manager to load OV1 from the default drive (1 is the current value of 
the variable name); control then transfers to OV1. When OV1 finishes processing, 
control returns to the statement following the invocation. 


In this example, the variable name is assigned the value ‘OV1’. However, you could 
also supply the overlay name as a character string from some other source, such as 
the console keyboard. 


The following constraints apply to overlay method two: 


® You can specify a drive code so the Overlay Manager can load overlays from 
drives other than the default drive. If you do not specify a drive code, the 
Overlay Manager uses the default drive as described in method one. 


= If you pass any parameters to the overlay, they must agree in number and type 
with the parameters that the overlay expects. 
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20.2.3 General Overlay Constraints 


The following general constraints apply when creating overlays in a PL/I program: 


20.3 


Each overlay has only one entry point. The Overlay Manager in the PL/I Run- 
time Subroutine Library assumes that this entry point is at the load address of 
the overlay. 


You cannot make an upward reference from a module to entry points in overlays 
higher on the tree. The only exception is a reference to the main entry point of 
the overlay. You can make downward references to entry points in overlays 
lower on the tree or in the root module. 


Common segments (EXTERNALS in PL/I) that are declared in one module 
cannot be initialized by a module higher in the tree. The linkage editor ignores 
any attempt to do so. 


You can nest overlays to a depth of five levels. 


The Overlay Manager uses the default buffer located at 80H, so user programs 
should not depend on data stored in this buffer. Note that in the 8086 implemen- 
tation, the default buffer is at 80H relative to the base of the Data segment. 


Command Line Syntax 


To specify overlays in the command line of the linkage editor, enclose each overlay 
specification in parentheses. You can create overlays with LINK-80 in one of the 
following forms: 


link root(ov1) 


link root(ov1,part2,part3) 


link root(ov1 = part1,part2,part3) 


The first form produces the file OV1.OVL from the file OV1.REL. The second form 
produces the file OV1.OVL from OV1.REL, PART2.REL, and PART3.REL. The third 
form produces the file OV1.OVL from PART1.REL, PART2.REL, and PART3.REL. 
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Create overlays with LINK-86 using the same forms: 

link86 root(ov1) 
link86 root(ov1,part2,part3) 
link86 root(ov1 = part1,part2,part3) 

The first form produces the file OV1.OVR from the file OV1.OBJ. The second form 
produces the file OV1.OVR from OV1.OBJ, PART2.OBJ, and PART3.OBJ. The third 
form produces the file OV1.OVR from PART1.OBJ, PART2.OBJ, and PART3.OBJ. 

In the command line, a left parenthesis indicates the start of a new overlay specifi- 
cation, and also indicates the end of the group preceding it. All files to be included at 
any point on the tree must appear together, without any intervening overlay specifi- 
cations. You can use spaces to improve readability, but do not use commas to set off 
the overlay specifications from the root module or from each other. 

For example, the following command line is invalid: 

A>link root(ovl) smoreroot 
The correct command is as follows: 
A>link root smoreroot(ovl) 

To nest overlays, you must specify them in the command line with nested parentheses. 

For example, the following command line creates the overlay system shown in Figure 


20-2: 


A?link menu(funel (subl)(sub 2)) (fune2) (funed (sub3)(subd)) 


End of Section 20 
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